{"id":15019522,"url":"https://github.com/srav001/vue-subscription","last_synced_at":"2026-02-27T05:05:43.806Z","repository":{"id":147124128,"uuid":"617081393","full_name":"srav001/vue-subscription","owner":"srav001","description":"A type-safe 🔥 \u0026 tiny ⭐️ super-charged ref ⚡️ in Vue 💚.","archived":false,"fork":false,"pushed_at":"2023-07-29T15:33:33.000Z","size":106,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-22T18:03:04.206Z","etag":null,"topics":["event-driven","eventbus","events","javascript","observable","observer","observer-pattern","subscribe","subscription","subscriptions","typescript","vue","vue3","vuejs","vuejs-library","vuejs-plugin","vuejs2"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/vue-subscription","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srav001.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-21T17:00:42.000Z","updated_at":"2023-07-07T14:32:38.000Z","dependencies_parsed_at":"2024-09-24T21:00:43.715Z","dependency_job_id":null,"html_url":"https://github.com/srav001/vue-subscription","commit_stats":{"total_commits":59,"total_committers":2,"mean_commits":29.5,"dds":"0.30508474576271183","last_synced_commit":"898460ca486c2e515f6d320e710ec5521c56ebc5"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/srav001/vue-subscription","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srav001%2Fvue-subscription","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srav001%2Fvue-subscription/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srav001%2Fvue-subscription/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srav001%2Fvue-subscription/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srav001","download_url":"https://codeload.github.com/srav001/vue-subscription/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srav001%2Fvue-subscription/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29885801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-driven","eventbus","events","javascript","observable","observer","observer-pattern","subscribe","subscription","subscriptions","typescript","vue","vue3","vuejs","vuejs-library","vuejs-plugin","vuejs2"],"created_at":"2024-09-24T19:53:38.744Z","updated_at":"2026-02-27T05:05:43.790Z","avatar_url":"https://github.com/srav001.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vue-subscription\n\nA type-safe 🔥 and tiny ⭐️ super-charged ref ⚡️ or eventBus replacement in Vue 💚. Compatible with Vue 2 ( 2.7.0 and above ) and Vue 3. Provides ESM and Common JS exports.\n\nFind it on `npm` - https://www.npmjs.com/package/vue-subscription.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Type-Definition](#type-definition)\n- [TLDR](#tldr)\n- [Demo](#demo)\n\n## Introduction\n\nOnly 1.3 kB or gzip: 0.7 kB in size, the [useSubscription](#tldr) composable takes an initial value and returns an object with a reactive value that is by default shallow and only deep when explicitly enabled. The value property, `$value is not automatically unwrapped in template`. Additionally, it also provides `explicit getter and setter` if you like more control over the state.\n\nThe package also provides a simple way to create reactive subscriptions that can be used to observe changes to a value and execute a list of subscribers when the value changes. It also includes methods to mutate the value for complex objects and trigger subscribers manually if and when needed rarely. Check out the [usage](#usage) examples.\n\n## Installation\n\nTo use this package, you can install it via npm (or yarn or pnpm):\n\n```sh\n# In your console\nnpm install vue-subscription\n```\n\n```typescript\n// In your file\nimport { useSubscription } from 'vue-subscription';\nconst mySubscription = useSubscription('hello'); // Type will be string\n```\n\n## API\n\n### Using in template\n\nTo display the state in template, you can either use the `$read` or `$get`. If you need 2-way data binding you can also use `$value`.\n\n```vue\n\u003ctemplate\u003e\n\t\u003cdiv\u003e{{ mySubscription.$value }}\u003c/div\u003e\n\t\u003c!-- Readonly version of the state --\u003e\n\t\u003cdiv\u003e{{ mySubscription.$get() }}\u003c/div\u003e\n\t\u003cdiv\u003e{{ mySubscription.$read.value }}\u003c/div\u003e\n\u003c/template\u003e\n```\n\n### $value / $get()\n\nThis property/method returns the current value of the subscription.\n\n```typescript\nconst value = mySubscription.$value;\nconst value = mySubscription.$get();\n```\n\n### $value = val / $set(val)\n\nThis property/method sets the current value of the subscription. Also the $set can be passed down a child component to update the state in parent.\n\n```typescript\nmySubscription.$value = 42;\nmySubscription.$set(42);\n```\n\nThe $set method can also accept a mutator function that takes the current value as an argument and returns the new value:\n\n```typescript\nmySubscription.$set(value =\u003e value + 1);\n```\n\n### $read\n\nThis is a read-only version of the subscription value. It wraps the subscription in a readonly ref.\n\n```typescript\nconst readonlySubscription = mySubscription.$read;\nconsole.log(readonlySubscription.value);\n```\n\n### $addSub\n\nThis method adds a subscriber to the subscription. A subscriber is a function that takes the new value as an argument and is executed whenever the value changes. The subscriber can be an `async` function. It is cleaned up automatically inside components.\n\n```typescript\nfunction logValue(value) {\n\tconsole.log(`New value: ${value}`);\n}\n\nmySubscription.$addSub(logValue);\n```\n\n### $deleteSub\n\nThis method removes a subscriber from the subscription.\n\n```typescript\nsubscription.$deleteSub(logValue);\n```\n\n### $clearSubs\n\nClears all subscribers. Easy for cleanup in beforeUnmount.\n\n```typescript\nsubscription.$clearSubs();\n```\n\n### $triggerSubs\n\nThis method manually triggers all subscribers to the subscription. Should only be needed rarely.\n\n```typescript\nsubscription.$triggerSubs();\n```\n\n### $mutate\n\nThis method mutates the subscription value with a mutator function. The mutator function takes the current value as an argument and returns the new value.\n\n```typescript\nsubscription.$mutate(value =\u003e {\n\tvalue.name = 'John';\n\treturn value;\n});\n```\n\n## Usage\n\nAll examples given below can be copy pasted into a file and tried out if needed.\n\n### Basic Example\n\n```typescript\nconst mySubscription = useSubscription('hello'); // Type will be string\n\n// Get the current value\nconsole.log(mySubscription.$value); // 'hello'\n\n// Subscribers can `async`\nasync function mySubscriber(value: string) {\n\treturn new Promise((resolve, reject) =\u003e {\n\t\tsetTimeout(() =\u003e {\n\t\t\tconsole.log(`The value is now: ${value}`);\n\t\t}, 1);\n\t});\n}\n\n// Add a subscriber\nmySubscription.$addSub(mySubscriber);\n// Manually trigger the subscribers if needed(rarely)\nmySubscription.$triggerSubs(); // 'The value is now: hello'\n\n// Set the value\nmySubscription.$value = 'world';\n\n// Subscriber runs here -  'The value is now: world'\n\n// Remove a subscriber. It is cleaned up automatically inside components.\nmySubscription.$deleteSub(mySubscriber);\n// OR to remove all subs at once.\nmySubscription.$clearSubs();\n\n// Use the readonly version of the value\nconst myReadonlyValue = mySubscription.$read;\nconsole.log(myReadonlyValue.value); // 'world'\n```\n\n### Complex state\n\nExample uses a complex objects which won't be tracked deeply by default. Unless the subscription is used in template, watch, watchEffect or computed you don't need to add the deep flag.\n\n```typescript\nconst mySubscription = useSubscription(\n\t{\n\t\tuser: {\n\t\t\tname: 'John',\n\t\t\tisActive: false\n\t\t}\n\t},\n\t// You can pass `true` as the deep flag to make the subscription deeply reactive if used in templates\n\ttrue\n);\n// Add a subscriber\nmySubscription.$addSub(data =\u003e {\n\tconsole.log(`The data is now: ${JSON.stringify(data)}`);\n});\n\nfunction myMutator(data: typeof mySubscription.$value) {\n\tdata.user.isActive = true;\n\treturn data;\n}\n\n// Trigger the subscribers\nmySubscription.$triggerSubs(); // 'The data is now: { user: { name: 'John', isActive: false }}'\n\nfunction tester() {\n\t// Mutate the value (only works if the value is an object)\n\tmySubscription.$mutate(myMutator);\n\t// Subscriber runs here -  'The data is now: { user: { name: 'John', isActive: true }}'\n}\ntester();\n```\n\n### Destructured ( Getter and Setter )\n\nYou can also destructure the properties to have a seperate getter and setter.\n\n```typescript\nconst { $get, $set, $read, $addSub } = useSubscription('hello');\n\n// Get the current value\nconsole.log($get()); // 'hello'\n\nfunction mySubscriber(value: string) {\n\tconsole.log(`The value is now: ${value}`);\n}\n\n// Add a subscriber\n$addSub(mySubscriber);\n\n// Set the value\n$set('world');\n\n// Subscriber runs here -  'The value is now: world'\n\n$set(val =\u003e `Hello ${val}`);\n// Subscriber runs here -  'The value is now: Hello world'\n\n// Use the readonly version of the value\nconsole.log($read.value); // 'Hello world'\n```\n\n## Type-Definition\n\n`T` is a generic.\n\n```typescript\nfunction useSubscription\u003cT\u003e(\n\tvalue: T,\n\tdeep?: boolean\n): {\n\t$value: T;\n\t$get: () =\u003e T;\n\t$set: (value: T | ((value: T) =\u003e T)) =\u003e void;\n\t$read: Readonly\u003cRef\u003cT\u003e\u003e;\n\t$addSub: (subscriber: (value: T) =\u003e Promise\u003cvoid\u003e | void) =\u003e void;\n\t$deleteSub: (subscriber: (value: T) =\u003e Promise\u003cvoid\u003e | void) =\u003e void;\n\t$clearSubs: () =\u003e void;\n\t$triggerSubs: () =\u003e void;\n\t$mutate: (mutator: (value: T) =\u003e T) =\u003e void;\n};\n```\n\n## TLDR\n\n### Arguments\n\nvalue - The initial value of the subscription. Throws an error if value is absent.\n\ndeep (optional) - Whether to create a shallow or deep reactive subscription. Defaults to false. Unless the subscription is used in template, watch, watchEffect or computed you don't need to add the deep flag.\n\n### Return Value\n\nAn object with the following properties (Type def above):\n\n- $value - The current value of the subscription. Doesn't unwrap in template.\n- $get - A function that returns the current value of the subscription.\n- $set - A function that sets the value of the subscription. If a function is passed, it will receive the current value of the subscription as its argument and should return the new value.\n- $read - A readonly reactive reference to the current value of the subscription.\n- $addSub - A method for adding a subscriber to the subscription. It can be `async`. The subscriber is a function that will be executed whenever the value of the subscription changes. It can provides the new value of the subscription as its argument and is cleaned up automatically inside components.\n- $deleteSub - A method for removing a subscriber from the subscription.\n- $clearSubs - A method for clearing all subscribers.\n- $triggerSubs - A method for manually triggering all subscribers. Should only be needed rarely.\n- $mutate - A method for updating the value of the subscription with a function that takes the current value as its argument and returns the new value. This should only be used for updating complex objects.\n\n## Demo\n\nThe demo shows the subscription being used with the eventBus APIs. You can checkout the demo to test locally or on StackBlitz. Make sure to run `npm install` in the root folder or copy the Vue components over from the demo here :-  \nhttps://github.com/srav001/vue-subscription/tree/main/demo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrav001%2Fvue-subscription","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrav001%2Fvue-subscription","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrav001%2Fvue-subscription/lists"}