@okikio/observables 1.0.2

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@okikio/observables",
+  "version": "1.0.2",
+  "description": "A spec-faithful yet ergonomic TC39-inspired Observable library with detailed types, tsdocs and examples.",
+  "keywords": [
+    "observable",
+    "observables",
+    "reactive",
+    "streams",
+    "tc39",
+    "web-streams",
+    "deno",
+    "node",
+    "bun"
+  ],
+  "author": "okikio",
+  "homepage": "https://github.com/okikio/observables#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/okikio/observables.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/okikio/observables/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    },
+    "./error": {
+      "import": "./esm/error.js",
+      "require": "./script/error.js"
+    },
+    "./types": {
+      "import": "./esm/_types.js",
+      "require": "./script/_types.js"
+    },
+    "./events": {
+      "import": "./esm/events.js",
+      "require": "./script/events.js"
+    },
+    "./queue": {
+      "import": "./esm/queue.js",
+      "require": "./script/queue.js"
+    },
+    "./observable": {
+      "import": "./esm/observable.js",
+      "require": "./script/observable.js"
+    },
+    "./operators": {
+      "import": "./esm/helpers/mod.js",
+      "require": "./script/helpers/mod.js"
+    },
+    "./operations": {
+      "import": "./esm/helpers/operations/mod.js",
+      "require": "./script/helpers/operations/mod.js"
+    },
+    "./operations/batch": {
+      "import": "./esm/helpers/operations/batch.js",
+      "require": "./script/helpers/operations/batch.js"
+    },
+    "./operations/combination": {
+      "import": "./esm/helpers/operations/combination.js",
+      "require": "./script/helpers/operations/combination.js"
+    },
+    "./operations/conditional": {
+      "import": "./esm/helpers/operations/conditional.js",
+      "require": "./script/helpers/operations/conditional.js"
+    },
+    "./operations/errors": {
+      "import": "./esm/helpers/operations/errors.js",
+      "require": "./script/helpers/operations/errors.js"
+    },
+    "./operations/timing": {
+      "import": "./esm/helpers/operations/timing.js",
+      "require": "./script/helpers/operations/timing.js"
+    },
+    "./operations/core": {
+      "import": "./esm/helpers/operations/core.js",
+      "require": "./script/helpers/operations/core.js"
+    }
+  },
+  "scripts": {},
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/_dnt.polyfills.d.ts

@@ -0,0 +1,20 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};
+declare global {
+    interface PromiseConstructor {
+        /**
+         * Creates a Promise that can be resolved or rejected using provided functions.
+         * @returns An object containing `promise` promise object, `resolve` and `reject` functions.
+         */
+        withResolvers<T>(): {
+            promise: Promise<T>;
+            resolve: (value: T | PromiseLike<T>) => void;
+            reject: (reason?: any) => void;
+        };
+    }
+}
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/script/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC;AACV,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,kBAAkB;QAC1B;;;WAGG;QACH,aAAa,CAAC,CAAC,KAAK;YAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;YAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;YAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;SAAE,CAAC;KAC3H;CACF"}

package/script/_dnt.polyfills.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// https://github.com/tc39/proposal-promise-with-resolvers/blob/3a78801e073e99217dbeb2c43ba7212f3bdc8b83/polyfills.js#L1C1-L9C2
+if (Promise.withResolvers === undefined) {
+    Promise.withResolvers = () => {
+        const out = {};
+        out.promise = new Promise((resolve_, reject_) => {
+            out.resolve = resolve_;
+            out.reject = reject_;
+        });
+        return out;
+    };
+}

package/script/_spec.d.ts

@@ -0,0 +1,260 @@
+import type { Symbol } from "./symbol.js";
+/**
+ * Defines the minimal contract for subscribable objects in the Observable ecosystem.
+ *
+ * ObservableProtocol is the core interface that all Observable-like objects must
+ * implement. It represents the object returned by `[Symbol.observable]()` that
+ * consumers actually call `.subscribe()` on.
+ *
+ * This interface is designed for interoperability between different Observable
+ * implementations, allowing libraries to work with any object that conforms to
+ * this protocol.
+ *
+ * In the TC39 proposal, this is the interface that the object returned by
+ * `[Symbol.observable]()` must satisfy.
+ *
+ * @typeParam T - Type of values emitted by this Observable.
+ *
+ * @example
+ * ```ts
+ * // Example of an object implementing ObservableProtocol
+ * const source: ObservableProtocol<number> = {
+ *   subscribe(observer) {
+ *     observer.next?.(1);
+ *     observer.next?.(2);
+ *     observer.complete?.();
+ *     return { unsubscribe() {} };
+ *   }
+ * };
+ *
+ * // Using the protocol
+ * const subscription = source.subscribe({
+ *   next: value => console.log(value)
+ * });
+ * ```
+ */
+export interface ObservableProtocol<T> {
+    /**
+     * Subscribes to this Observable with an observer object.
+     *
+     * This method is the primary way to consume values from an Observable.
+     * It begins the subscription process, connecting the consumer (observer)
+     * to the producer, and returns a subscription object that can be used
+     * to cancel the subscription.
+     *
+     * @param observer - Object with callback methods to handle notifications
+     * @returns A subscription object for cancellation
+     *
+     * @specref § 3.1 Observable.prototype.subscribe
+     */
+    subscribe(observer: SpecObserver<T>): SpecSubscription;
+    /**
+     * Subscribes to this Observable with individual callback functions.
+     *
+     * This is a convenience overload that allows subscribing with individual
+     * functions instead of an observer object. Internally, these callbacks
+     * are wrapped into an observer object.
+     *
+     * @param next - Function to handle each emitted value
+     * @param error - Optional function to handle errors
+     * @param complete - Optional function to handle completion
+     * @returns A subscription object for cancellation
+     *
+     * @specref § 3.1 Observable.prototype.subscribe
+     */
+    subscribe(next: (value: T) => void, error?: (error: unknown) => void, complete?: () => void): SpecSubscription;
+}
+/**
+ * Represents a cancellable connection to an Observable.
+ *
+ * A SpecSubscription is returned by the `subscribe` method and provides
+ * a way to cancel the subscription, stopping the delivery of values and
+ * releasing any resources associated with it.
+ *
+ * This interface is intentionally minimal, matching the TC39 proposal's
+ * requirements for subscription objects.
+ *
+ * @example
+ * ```ts
+ * const subscription = observable.subscribe({
+ *   next: value => console.log(value)
+ * });
+ *
+ * // Later, to cancel:
+ * subscription.unsubscribe();
+ * ```
+ */
+export interface SpecSubscription {
+    /**
+     * Cancels the subscription and releases associated resources.
+     *
+     * When called:
+     * - Execution of the Observable is stopped
+     * - No further notifications are delivered to the observer
+     * - Resources associated with the subscription are released
+     * - If already closed (unsubscribed, errored, or completed), this is a no-op
+     *
+     * This method is idempotent - calling it multiple times has the same
+     * effect as calling it once.
+     *
+     * @specref § 4.2.2 %SubscriptionPrototype%.unsubscribe
+     */
+    unsubscribe(): void;
+}
+/**
+ * Defines a consumer of Observable notifications.
+ *
+ * An Observer is an object with optional callback methods that receive
+ * notifications from an Observable:
+ * - `next`: Called for each value emitted by the Observable
+ * - `error`: Called when an error occurs (terminal)
+ * - `complete`: Called when the Observable finishes normally (terminal)
+ * - `start`: Called immediately after subscription is established
+ *
+ * All methods are optional. If a method is missing, the corresponding
+ * notification is effectively ignored.
+ *
+ * @typeParam T - Type of values this observer can receive.
+ *
+ * @example
+ * ```ts
+ * const observer: SpecObserver<number> = {
+ *   start(subscription) {
+ *     console.log('Starting subscription');
+ *     // Save subscription reference if needed later
+ *   },
+ *   next(value) {
+ *     console.log('Received value:', value);
+ *   },
+ *   error(err) {
+ *     console.error('Error occurred:', err);
+ *   },
+ *   complete() {
+ *     console.log('Observable completed');
+ *   }
+ * };
+ *
+ * observable.subscribe(observer);
+ * ```
+ */
+export interface SpecObserver<T> {
+    /**
+     * Called immediately after subscription is established.
+     *
+     * This callback:
+     * - Receives the subscription object as a parameter
+     * - Runs before any other observer methods
+     * - Allows the observer to store the subscription for later cancellation
+     * - Can throw exceptions, which are reported but don't prevent subscription
+     *
+     * If this method throws, the error is reported to the host environment
+     * but the subscription is still established.
+     *
+     * @param subscription - The subscription object created by this subscribe call
+     * @specref § 4.2 CreateSubscription
+     */
+    start?(subscription: SpecSubscription): void;
+    /**
+     * Receives the next value in the sequence.
+     *
+     * This is the main data channel of an Observable. It:
+     * - Is called zero or more times, once per emitted value
+     * - Receives each value as its only parameter
+     * - Is never called after error or complete
+     * - Is never called after unsubscribe
+     *
+     * If this method throws, the error is delivered to the `error` method.
+     *
+     * @param value - The value emitted by the Observable
+     * @specref § 5.2.4 %SubscriptionObserverPrototype%.next
+     */
+    next?(value: T): void;
+    /**
+     * Handles an error notification.
+     *
+     * This is called when:
+     * - The Observable encounters an error during execution
+     * - The observer's next or complete methods throw
+     *
+     * After this method is called:
+     * - The subscription is considered closed
+     * - No more notifications will be delivered
+     * - Resources associated with the subscription are released
+     *
+     * If this method throws, the error is reported to the host environment.
+     *
+     * @param error - The error that occurred
+     * @specref § 5.2.5 %SubscriptionObserverPrototype%.error
+     */
+    error?(error: unknown): void;
+    /**
+     * Handles successful completion of the Observable.
+     *
+     * This is called when:
+     * - The Observable has finished emitting values normally
+     * - No more values will be emitted
+     *
+     * After this method is called:
+     * - The subscription is considered closed
+     * - No more notifications will be delivered
+     * - Resources associated with the subscription are released
+     *
+     * If this method throws, the error is delivered to the `error` method.
+     *
+     * @specref § 5.2.6 %SubscriptionObserverPrototype%.complete
+     */
+    complete?(): void;
+}
+/**
+ * Defines an object that can be converted to an Observable.
+ *
+ * This interface represents anything that has a `[Symbol.observable]()` method,
+ * making it interoperable with the Observable ecosystem. It's the TypeScript
+ * equivalent of the TC39 proposal's "Observable-like" concept.
+ *
+ * The method must return an ObservableProtocol that can be subscribed to.
+ * This enables interoperability between different Observable implementations
+ * and allows conversion of custom types to Observables.
+ *
+ * @typeParam T - Type of values the resulting Observable will emit.
+ *
+ * @example
+ * ```ts
+ * // A simple string sequence as an Observable-like
+ * const greetings: SpecObservable<string> = {
+ *   [Symbol.observable]() {
+ *     return {
+ *       subscribe(observer) {
+ *         observer.next?.('Hello');
+ *         observer.next?.('World');
+ *         observer.complete?.();
+ *         return { unsubscribe() {} };
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * // Convert to an Observable
+ * const observable = Observable.from(greetings);
+ * ```
+ *
+ * @see https://tc39.es/proposal-observable/#observable-interface
+ * @specref § 3.3 Observable.prototype[@@observable]
+ */
+export interface SpecObservable<T> {
+    /**
+     * Returns an object that conforms to the ObservableProtocol.
+     *
+     * This method acts as a conversion point that transforms any object
+     * into an Observable-like entity that can be subscribed to.
+     *
+     * When called:
+     * - It should return an object with a `subscribe` method
+     * - That object must conform to the ObservableProtocol interface
+     * - The returned object becomes the actual subscription target
+     *
+     * @returns An ObservableProtocol that can be subscribed to
+     */
+    [Symbol.observable](): ObservableProtocol<T>;
+}
+//# sourceMappingURL=_spec.d.ts.map

package/script/_spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_spec.d.ts","sourceRoot":"","sources":["../src/_spec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;IAEvD;;;;;;;;;;;;;OAaG;IACH,SAAS,CACP,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EACxB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,gBAAgB,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE7C;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;;;;;;;;;OAYG;IACH,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;CAC9C"}

package/script/_spec.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/_types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Public observer and subscription types for the Observable entrypoints.
+ *
+ * This module collects the runtime-facing interfaces that show up whenever you
+ * subscribe to an Observable. It defines the enhanced `Observer<T>` and
+ * `Subscription` shapes used by this package, then re-exports the lower-level
+ * spec types from `./_spec.ts` for callers that need proposal-aligned building
+ * blocks.
+ *
+ * Use this entrypoint when you are writing libraries, adapters, or tests that
+ * need to talk about Observable contracts without importing the full runtime
+ * implementation. In day-to-day app code, you will usually consume these types
+ * indirectly through `Observable`, `EventBus`, or operator helpers. They live
+ * here so the public type surface stays easy to find and stable across
+ * entrypoints.
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+import type { SpecObserver, SpecSubscription } from "./_spec.js";
+import type { Symbol } from "./symbol.js";
+/**
+ * Enhanced Observer interface for our implementation.
+ *
+ * This extends the minimal SpecObserver with additional capabilities and
+ * type-safety for our specific Observable implementation. It provides:
+ *
+ * 1. Type-safe access to our enhanced Subscription object
+ * 2. Consistent method signatures for notification handling
+ * 3. Same optional methods as the spec but with our own types
+ *
+ * While the base spec only requires minimal functionality, our extended
+ * Observer provides more guarantees and features.
+ *
+ * @typeParam T - Type of values this observer can receive.
+ *
+ * @example
+ * ```ts
+ * import { Observable } from './observable.ts';
+ * import type { Observer, Subscription } from './_types.ts';
+ *
+ * const timerObserver: Observer<number> = {
+ *   start(subscription) {
+ *     console.log('Timer started');
+ *     // Can access enhanced subscription properties
+ *     console.log('Subscription active:', !subscription.closed);
+ *   },
+ *   next(value) {
+ *     console.log('Tick:', value);
+ *   },
+ *   complete() {
+ *     console.log('Timer completed');
+ *   }
+ * };
+ * ```
+ */
+export interface Observer<T> extends SpecObserver<T> {
+    /**
+     * Called immediately after subscribing with our enhanced Subscription type.
+     *
+     * This override ensures the subscription passed to start() is our
+     * enhanced Subscription type with additional properties and methods,
+     * not just the minimal SpecSubscription.
+     *
+     * @param subscription - Our enhanced Subscription object
+     * @specref § 4.2 CreateSubscription
+     */
+    start?(subscription: Subscription): void;
+}
+/**
+ * Enhanced Subscription interface with additional features.
+ *
+ * Extends the minimal SpecSubscription with:
+ * 1. A `closed` property to check subscription state
+ * 2. Support for `using` blocks via Symbol.dispose
+ * 3. Support for async cleanup via Symbol.asyncDispose
+ * 4. String tag for proper toString() behavior
+ *
+ * These enhancements make subscriptions more useful and ergonomic
+ * while maintaining compatibility with the core specification.
+ *
+ * @example
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * const source = Observable.of(1, 2, 3);
+ *
+ * // Standard usage
+ * const sub = source.subscribe((value) => console.log(value));
+ * console.log('Active:', !sub.closed);
+ * sub.unsubscribe();
+ *
+ * // With using blocks (automatically unsubscribes at block end)
+ * {
+ *   using sub = source.subscribe((value) => console.log(value));
+ *   // Use subscription here...
+ * } // Subscription cleaned up here
+ *
+ * // With async using blocks
+ * async function example() {
+ *   await using sub = source.subscribe((value) => console.log(value));
+ *   // Use subscription here...
+ * } // Awaits cleanup here
+ * ```
+ */
+export interface Subscription extends SpecSubscription, Disposable, AsyncDisposable {
+    /**
+     * Indicates whether this subscription is closed.
+     *
+     * A subscription becomes closed when:
+     * - `unsubscribe()` is called explicitly
+     * - The Observable calls observer.error()
+     * - The Observable calls observer.complete()
+     *
+     * Once closed, a subscription cannot be reopened, and no further
+     * notifications will be delivered to the observer.
+     *
+     * @example
+     * ```ts
+     * import { Observable } from './observable.ts';
+     *
+     * const obs = Observable.of(1, 2, 3);
+     * const sub = obs.subscribe(() => {});
+     * console.log(sub.closed); // false
+     *
+     * sub.unsubscribe();
+     * console.log(sub.closed); // true
+     * ```
+     */
+    readonly closed: boolean;
+    /**
+     * Provides a standard string tag for the object.
+     *
+     * Used by Object.prototype.toString to identify this object type.
+     * This ensures that `Object.prototype.toString.call(subscription)`
+     * returns "[object Subscription]".
+     */
+    readonly [Symbol.toStringTag]: "Subscription";
+}
+export type * from "./_spec.js";
+//# sourceMappingURL=_types.d.ts.map

package/script/_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../src/_types.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAClD;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,YACf,SAAQ,gBAAgB,EAAE,UAAU,EAAE,eAAe;IACrD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBzB;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;CAC/C;AAED,mBAAmB,YAAY,CAAC"}

package/script/_types.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// @filename: _types.ts
+/**
+ * Public observer and subscription types for the Observable entrypoints.
+ *
+ * This module collects the runtime-facing interfaces that show up whenever you
+ * subscribe to an Observable. It defines the enhanced `Observer<T>` and
+ * `Subscription` shapes used by this package, then re-exports the lower-level
+ * spec types from `./_spec.ts` for callers that need proposal-aligned building
+ * blocks.
+ *
+ * Use this entrypoint when you are writing libraries, adapters, or tests that
+ * need to talk about Observable contracts without importing the full runtime
+ * implementation. In day-to-day app code, you will usually consume these types
+ * indirectly through `Observable`, `EventBus`, or operator helpers. They live
+ * here so the public type surface stays easy to find and stable across
+ * entrypoints.
+ *
+ * @module
+ */
+require("./_dnt.polyfills.js");