{"id":13451974,"url":"https://github.com/tc39/proposal-observable","last_synced_at":"2025-05-15T08:07:11.151Z","repository":{"id":31327777,"uuid":"34890311","full_name":"tc39/proposal-observable","owner":"tc39","description":"Observables for ECMAScript","archived":false,"fork":false,"pushed_at":"2019-11-01T06:49:54.000Z","size":480,"stargazers_count":3097,"open_issues_count":47,"forks_count":91,"subscribers_count":179,"default_branch":"master","last_synced_at":"2025-04-14T14:59:36.314Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tc39.github.io/proposal-observable/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tc39.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-01T05:00:12.000Z","updated_at":"2025-04-13T16:54:41.000Z","dependencies_parsed_at":"2022-07-28T08:48:50.274Z","dependency_job_id":null,"html_url":"https://github.com/tc39/proposal-observable","commit_stats":null,"previous_names":["zenparsing/es-observable"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-observable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-observable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-observable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-observable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tc39","download_url":"https://codeload.github.com/tc39/proposal-observable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301433,"owners_count":22047904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-07-31T07:01:08.864Z","updated_at":"2025-05-15T08:07:11.071Z","avatar_url":"https://github.com/tc39.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","The Observable Standard"],"sub_categories":["Podcasts"],"readme":"## ECMAScript Observable ##\n\nThis proposal introduces an **Observable** type to the ECMAScript standard library.\nThe **Observable** type can be used to model push-based data sources such as DOM\nevents, timer intervals, and sockets.  In addition, observables are:\n\n- *Compositional*: Observables can be composed with higher-order combinators.\n- *Lazy*: Observables do not start emitting data until an **observer** has subscribed.\n\n### Example: Observing Keyboard Events ###\n\nUsing the **Observable** constructor, we can create a function which returns an\nobservable stream of events for an arbitrary DOM element and event type.\n\n```js\nfunction listen(element, eventName) {\n    return new Observable(observer =\u003e {\n        // Create an event handler which sends data to the sink\n        let handler = event =\u003e observer.next(event);\n\n        // Attach the event handler\n        element.addEventListener(eventName, handler, true);\n\n        // Return a cleanup function which will cancel the event stream\n        return () =\u003e {\n            // Detach the event handler from the element\n            element.removeEventListener(eventName, handler, true);\n        };\n    });\n}\n```\n\nWe can then use standard combinators to filter and map the events in the stream,\njust like we would with an array.\n\n```js\n// Return an observable of special key down commands\nfunction commandKeys(element) {\n    let keyCommands = { \"38\": \"up\", \"40\": \"down\" };\n\n    return listen(element, \"keydown\")\n        .filter(event =\u003e event.keyCode in keyCommands)\n        .map(event =\u003e keyCommands[event.keyCode])\n}\n```\n\n*Note: The \"filter\" and \"map\" methods are not included in this proposal.  They may\nbe added in a future version of this specification.*\n\nWhen we want to consume the event stream, we subscribe with an **observer**.\n\n```js\nlet subscription = commandKeys(inputElement).subscribe({\n    next(val) { console.log(\"Received key command: \" + val) },\n    error(err) { console.log(\"Received an error: \" + err) },\n    complete() { console.log(\"Stream complete\") },\n});\n```\n\nThe object returned by **subscribe** will allow us to cancel the subscription at any time.\nUpon cancelation, the Observable's cleanup function will be executed.\n\n```js\n// After calling this function, no more events will be sent\nsubscription.unsubscribe();\n```\n\n### Motivation ###\n\nThe Observable type represents one of the fundamental protocols for processing asynchronous\nstreams of data.  It is particularly effective at modeling streams of data which originate\nfrom the environment and are pushed into the application, such as user interface events. By\noffering Observable as a component of the ECMAScript standard library, we allow platforms\nand applications to share a common push-based stream protocol.\n\n### Implementations ###\n\n- [RxJS 5](https://github.com/ReactiveX/RxJS)\n- [core-js](https://github.com/zloirock/core-js#observable)\n- [zen-observable](https://github.com/zenparsing/zen-observable)\n- [fate-observable](https://github.com/shanewholloway/node-fate-observable)\n\n### Running Tests ###\n\nTo run the unit tests, install the **es-observable-tests** package into your project.\n\n```\nnpm install es-observable-tests\n```\n\nThen call the exported `runTests` function with the constructor you want to test.\n\n```js\nrequire(\"es-observable-tests\").runTests(MyObservable);\n```\n\n### API ###\n\n#### Observable ####\n\nAn Observable represents a sequence of values which may be observed.\n\n```js\ninterface Observable {\n\n    constructor(subscriber : SubscriberFunction);\n\n    // Subscribes to the sequence with an observer\n    subscribe(observer : Observer) : Subscription;\n\n    // Subscribes to the sequence with callbacks\n    subscribe(onNext : Function,\n              onError? : Function,\n              onComplete? : Function) : Subscription;\n\n    // Returns itself\n    [Symbol.observable]() : Observable;\n\n    // Converts items to an Observable\n    static of(...items) : Observable;\n\n    // Converts an observable or iterable to an Observable\n    static from(observable) : Observable;\n\n}\n\ninterface Subscription {\n\n    // Cancels the subscription\n    unsubscribe() : void;\n\n    // A boolean value indicating whether the subscription is closed\n    get closed() : Boolean;\n}\n\nfunction SubscriberFunction(observer: SubscriptionObserver) : (void =\u003e void)|Subscription;\n```\n\n#### Observable.of ####\n\n`Observable.of` creates an Observable of the values provided as arguments.  The values\nare delivered synchronously when `subscribe` is called.\n\n```js\nObservable.of(\"red\", \"green\", \"blue\").subscribe({\n    next(color) {\n        console.log(color);\n    }\n});\n\n/*\n \u003e \"red\"\n \u003e \"green\"\n \u003e \"blue\"\n*/\n```\n\n#### Observable.from ####\n\n`Observable.from` converts its argument to an Observable.\n\n- If the argument has a `Symbol.observable` method, then it returns the result of\n  invoking that method.  If the resulting object is not an instance of Observable,\n  then it is wrapped in an Observable which will delegate subscription.\n- Otherwise, the argument is assumed to be an iterable and the iteration values are\n  delivered synchronously when `subscribe` is called.\n\nConverting from an object which supports `Symbol.observable` to an Observable:\n\n```js\nObservable.from({\n    [Symbol.observable]() {\n        return new Observable(observer =\u003e {\n            setTimeout(() =\u003e {\n                observer.next(\"hello\");\n                observer.next(\"world\");\n                observer.complete();\n            }, 2000);\n        });\n    }\n}).subscribe({\n    next(value) {\n        console.log(value);\n    }\n});\n\n/*\n \u003e \"hello\"\n \u003e \"world\"\n*/\n\nlet observable = new Observable(observer =\u003e {});\nObservable.from(observable) === observable; // true\n\n```\n\nConverting from an iterable to an Observable:\n\n```js\nObservable.from([\"mercury\", \"venus\", \"earth\"]).subscribe({\n    next(value) {\n        console.log(value);\n    }\n});\n\n/*\n \u003e \"mercury\"\n \u003e \"venus\"\n \u003e \"earth\"\n*/\n```\n\n#### Observer ####\n\nAn Observer is used to receive data from an Observable, and is supplied as an\nargument to **subscribe**.\n\nAll methods are optional.\n\n```js\ninterface Observer {\n\n    // Receives the subscription object when `subscribe` is called\n    start(subscription : Subscription);\n\n    // Receives the next value in the sequence\n    next(value);\n\n    // Receives the sequence error\n    error(errorValue);\n\n    // Receives a completion notification\n    complete();\n}\n```\n\n#### SubscriptionObserver ####\n\nA SubscriptionObserver is a normalized Observer which wraps the observer object supplied to\n**subscribe**.\n\n```js\ninterface SubscriptionObserver {\n\n    // Sends the next value in the sequence\n    next(value);\n\n    // Sends the sequence error\n    error(errorValue);\n\n    // Sends the completion notification\n    complete();\n\n    // A boolean value indicating whether the subscription is closed\n    get closed() : Boolean;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-observable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftc39%2Fproposal-observable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-observable/lists"}