@amazon/vinyl-observable 1.0.0

package/dist/types/ts3.7/observable/observableValue.d.ts

@@ -0,0 +1,153 @@
+import { Maybe, Unsubscribe } from '@amazon/vinyl-util';
+export interface ObservableValue<T> {
+    /**
+     * Invokes a callback immediately and when data has changed.
+     * @param callback
+     */
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    /**
+     * Creates a data provider transforming this data.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Returns a data provider for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): ObservableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): ObservableValue<unknown>;
+    /**
+     * The current value.
+     */
+    readonly value: T;
+    /**
+     * Gets the current value.
+     */
+    getValue(): T;
+    /**
+     * A monotonically increasing id that increments before each change notification.
+     */
+    readonly changeId: number;
+}
+export type MaybeObservableValue<T> = ObservableValue<T> | T;
+/**
+ * Given an ObservableValue<ValueType>, infers ValueType.
+ */
+export type InferObservableValueType<T extends ObservableValue<any>> = T extends ObservableValue<infer U> ? U : never;
+/**
+ * A mutable version of a data provider.
+ */
+export interface MutableValue<T> extends ObservableValue<T> {
+    /**
+     * The current value, may be set.
+     * `onData` callbacks will be invoked if value is not exactly equal to
+     * the current value.
+     */
+    value: T;
+    /**
+     * Sets the current value.
+     */
+    setValue(value: T): void;
+    /**
+     * Creates a readonly sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Creates a writable sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     * @param setData The reverse of transform; When the sub-controller's data is set, this will convert the
+     * transformed value back to what can be saved on `this` controller.
+     */
+    map<U>(transform: (value: T) => U, setData: (transformed: U, original: T) => T): MutableValue<U>;
+    /**
+     * Returns a data controller for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): MutableValue<unknown>;
+    /**
+     * Invokes subscribers, can be used to indicate a change without setting
+     * a new value.
+     */
+    invalidate(): void;
+}
+export type DataChangedCallback<T> = (
+/**
+ * The current value.
+ */
+value: T, 
+/**
+ * The previous value, or undefined if this is the first time calling this callback.
+ */
+previousValue: T | undefined) => void;
+export type Picked<T, K extends keyof NonNullable<T>> = T extends undefined | null ? NonNullable<T>[K] | undefined : NonNullable<T>[K];
+declare abstract class MutableValueBase<T> implements MutableValue<T> {
+    abstract value: T;
+    abstract readonly changeId: number;
+    getValue(): T;
+    setValue(value: T): void;
+    abstract onData(callback: DataChangedCallback<T>): Unsubscribe;
+    map<U>(transform: {
+        (value: T): U;
+    }, setData?: Maybe<(transformed: U, original: T) => T>): MutableValue<U>;
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    abstract invalidate(): void;
+}
+export declare class MutableValueImpl<T> extends MutableValueBase<T> {
+    private currentValue;
+    private _disposed;
+    private currentIndex;
+    private n;
+    private readonly callbacks;
+    private _changeId;
+    constructor(currentValue: T);
+    get changeId(): number;
+    hasAnyListeners(): boolean;
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    get value(): T;
+    set value(value: T);
+    invalidate(): void;
+    get disposed(): boolean;
+    dispose(): void;
+    private notify;
+}
+/**
+ * Returns true if the value is a ObservableValue.
+ * @param value
+ */
+export declare function isObservableValue(value: any): value is ObservableValue<any>;
+/**
+ * Creates a data provider.
+ * @param value
+ */
+export declare function data<T>(value: T): MutableValueImpl<T>;
+/**
+ * If the value is a ObservableValue, returns the data provider as is. Otherwise, wraps the value in
+ * provider.
+ *
+ * @param value
+ */
+export declare function asData<T>(value: MaybeObservableValue<T>): ObservableValue<T>;
+export type OnDataRequested<T> = (setData: (value: T) => void) => Unsubscribe;
+export declare class ExternalMutableValue<T> extends MutableValueBase<T> {
+    private readonly onDataRequested;
+    private _data;
+    private externalDataSub;
+    constructor(currentValue: T, onDataRequested: OnDataRequested<T>);
+    get value(): T;
+    get changeId(): number;
+    set value(_value: T);
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    invalidate(): void;
+}
+/**
+ * Creates a data provider that can observe an external event system when onData is called.
+ *
+ * @param initialValue
+ * @param onDataRequested
+ */
+export declare function externalData<T>(initialValue: T, onDataRequested: (setData: (value: T) => void) => Unsubscribe): ObservableValue<T>;
+export {};
+//# sourceMappingURL=observableValue.d.ts.map

package/dist/types/ts4.1/index.d.ts

@@ -0,0 +1,4 @@
+/** Auto-generated from build scripts */
+export * from './observable/observableValue';
+export * from './observable/combineData';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.1/observable/combineData.d.ts

@@ -0,0 +1,11 @@
+import type { ObservableValue } from './observableValue';
+import type { ReadonlyRecord } from '@amazon/vinyl-util';
+/**
+ * Combines a record of data providers into a single provider of a record of values.
+ *
+ * @param inputs A record of data providers.
+ */
+export declare function combineData<T extends ReadonlyRecord<string, ObservableValue<unknown>>>(inputs: T): ObservableValue<{
+    readonly [K in keyof T]: T[K] extends ObservableValue<infer U> ? U : T[K];
+}>;
+//# sourceMappingURL=combineData.d.ts.map

package/dist/types/ts4.1/observable/observableValue.d.ts

@@ -0,0 +1,153 @@
+import type { Maybe, Unsubscribe } from '@amazon/vinyl-util';
+export interface ObservableValue<T> {
+    /**
+     * Invokes a callback immediately and when data has changed.
+     * @param callback
+     */
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    /**
+     * Creates a data provider transforming this data.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Returns a data provider for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): ObservableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): ObservableValue<unknown>;
+    /**
+     * The current value.
+     */
+    readonly value: T;
+    /**
+     * Gets the current value.
+     */
+    getValue(): T;
+    /**
+     * A monotonically increasing id that increments before each change notification.
+     */
+    readonly changeId: number;
+}
+export type MaybeObservableValue<T> = ObservableValue<T> | T;
+/**
+ * Given an ObservableValue<ValueType>, infers ValueType.
+ */
+export type InferObservableValueType<T extends ObservableValue<any>> = T extends ObservableValue<infer U> ? U : never;
+/**
+ * A mutable version of a data provider.
+ */
+export interface MutableValue<T> extends ObservableValue<T> {
+    /**
+     * The current value, may be set.
+     * `onData` callbacks will be invoked if value is not exactly equal to
+     * the current value.
+     */
+    value: T;
+    /**
+     * Sets the current value.
+     */
+    setValue(value: T): void;
+    /**
+     * Creates a readonly sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Creates a writable sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     * @param setData The reverse of transform; When the sub-controller's data is set, this will convert the
+     * transformed value back to what can be saved on `this` controller.
+     */
+    map<U>(transform: (value: T) => U, setData: (transformed: U, original: T) => T): MutableValue<U>;
+    /**
+     * Returns a data controller for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): MutableValue<unknown>;
+    /**
+     * Invokes subscribers, can be used to indicate a change without setting
+     * a new value.
+     */
+    invalidate(): void;
+}
+export type DataChangedCallback<T> = (
+/**
+ * The current value.
+ */
+value: T, 
+/**
+ * The previous value, or undefined if this is the first time calling this callback.
+ */
+previousValue: T | undefined) => void;
+export type Picked<T, K extends keyof NonNullable<T>> = T extends undefined | null ? NonNullable<T>[K] | undefined : NonNullable<T>[K];
+declare abstract class MutableValueBase<T> implements MutableValue<T> {
+    abstract value: T;
+    abstract readonly changeId: number;
+    getValue(): T;
+    setValue(value: T): void;
+    abstract onData(callback: DataChangedCallback<T>): Unsubscribe;
+    map<U>(transform: {
+        (value: T): U;
+    }, setData?: Maybe<(transformed: U, original: T) => T>): MutableValue<U>;
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    abstract invalidate(): void;
+}
+export declare class MutableValueImpl<T> extends MutableValueBase<T> {
+    private currentValue;
+    private _disposed;
+    private currentIndex;
+    private n;
+    private readonly callbacks;
+    private _changeId;
+    constructor(currentValue: T);
+    get changeId(): number;
+    hasAnyListeners(): boolean;
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    get value(): T;
+    set value(value: T);
+    invalidate(): void;
+    get disposed(): boolean;
+    dispose(): void;
+    private notify;
+}
+/**
+ * Returns true if the value is a ObservableValue.
+ * @param value
+ */
+export declare function isObservableValue(value: any): value is ObservableValue<any>;
+/**
+ * Creates a data provider.
+ * @param value
+ */
+export declare function data<T>(value: T): MutableValueImpl<T>;
+/**
+ * If the value is a ObservableValue, returns the data provider as is. Otherwise, wraps the value in
+ * provider.
+ *
+ * @param value
+ */
+export declare function asData<T>(value: MaybeObservableValue<T>): ObservableValue<T>;
+export type OnDataRequested<T> = (setData: (value: T) => void) => Unsubscribe;
+export declare class ExternalMutableValue<T> extends MutableValueBase<T> {
+    private readonly onDataRequested;
+    private _data;
+    private externalDataSub;
+    constructor(currentValue: T, onDataRequested: OnDataRequested<T>);
+    get value(): T;
+    get changeId(): number;
+    set value(_value: T);
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    invalidate(): void;
+}
+/**
+ * Creates a data provider that can observe an external event system when onData is called.
+ *
+ * @param initialValue
+ * @param onDataRequested
+ */
+export declare function externalData<T>(initialValue: T, onDataRequested: (setData: (value: T) => void) => Unsubscribe): ObservableValue<T>;
+export {};
+//# sourceMappingURL=observableValue.d.ts.map

package/dist/types/ts4.7/index.d.ts

@@ -0,0 +1,4 @@
+/** Auto-generated from build scripts */
+export * from './observable/observableValue';
+export * from './observable/combineData';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/observable/combineData.d.ts

@@ -0,0 +1,11 @@
+import { type ObservableValue } from './observableValue';
+import type { ReadonlyRecord } from '@amazon/vinyl-util';
+/**
+ * Combines a record of data providers into a single provider of a record of values.
+ *
+ * @param inputs A record of data providers.
+ */
+export declare function combineData<T extends ReadonlyRecord<string, ObservableValue<unknown>>>(inputs: T): ObservableValue<{
+    readonly [K in keyof T]: T[K] extends ObservableValue<infer U> ? U : T[K];
+}>;
+//# sourceMappingURL=combineData.d.ts.map

package/dist/types/ts4.7/observable/observableValue.d.ts

@@ -0,0 +1,153 @@
+import type { Maybe, Unsubscribe } from '@amazon/vinyl-util';
+export interface ObservableValue<out T> {
+    /**
+     * Invokes a callback immediately and when data has changed.
+     * @param callback
+     */
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    /**
+     * Creates a data provider transforming this data.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Returns a data provider for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): ObservableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): ObservableValue<unknown>;
+    /**
+     * The current value.
+     */
+    readonly value: T;
+    /**
+     * Gets the current value.
+     */
+    getValue(): T;
+    /**
+     * A monotonically increasing id that increments before each change notification.
+     */
+    readonly changeId: number;
+}
+export type MaybeObservableValue<T> = ObservableValue<T> | T;
+/**
+ * Given an ObservableValue<ValueType>, infers ValueType.
+ */
+export type InferObservableValueType<T extends ObservableValue<any>> = T extends ObservableValue<infer U> ? U : never;
+/**
+ * A mutable version of a data provider.
+ */
+export interface MutableValue<T> extends ObservableValue<T> {
+    /**
+     * The current value, may be set.
+     * `onData` callbacks will be invoked if value is not exactly equal to
+     * the current value.
+     */
+    value: T;
+    /**
+     * Sets the current value.
+     */
+    setValue(value: T): void;
+    /**
+     * Creates a readonly sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     */
+    map<U>(transform: (value: T) => U): ObservableValue<U>;
+    /**
+     * Creates a writable sub-controller for a transformed value.
+     *
+     * @param transform Applies a transformation to a single value using a provided function and returns the result.
+     * The returned sub controller will use this as its value.
+     * @param setData The reverse of transform; When the sub-controller's data is set, this will convert the
+     * transformed value back to what can be saved on `this` controller.
+     */
+    map<U>(transform: (value: T) => U, setData: (transformed: U, original: T) => T): MutableValue<U>;
+    /**
+     * Returns a data controller for a property of T.
+     */
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    pick(prop: PropertyKey): MutableValue<unknown>;
+    /**
+     * Invokes subscribers, can be used to indicate a change without setting
+     * a new value.
+     */
+    invalidate(): void;
+}
+export type DataChangedCallback<T> = (
+/**
+ * The current value.
+ */
+value: T, 
+/**
+ * The previous value, or undefined if this is the first time calling this callback.
+ */
+previousValue: T | undefined) => void;
+export type Picked<T, K extends keyof NonNullable<T>> = T extends undefined | null ? NonNullable<T>[K] | undefined : NonNullable<T>[K];
+declare abstract class MutableValueBase<T> implements MutableValue<T> {
+    abstract value: T;
+    abstract readonly changeId: number;
+    getValue(): T;
+    setValue(value: T): void;
+    abstract onData(callback: DataChangedCallback<T>): Unsubscribe;
+    map<U>(transform: {
+        (value: T): U;
+    }, setData?: Maybe<(transformed: U, original: T) => T>): MutableValue<U>;
+    pick<K extends keyof NonNullable<T>>(prop: K): MutableValue<Picked<T, K>>;
+    abstract invalidate(): void;
+}
+export declare class MutableValueImpl<T> extends MutableValueBase<T> {
+    private currentValue;
+    private _disposed;
+    private currentIndex;
+    private n;
+    private readonly callbacks;
+    private _changeId;
+    constructor(currentValue: T);
+    get changeId(): number;
+    hasAnyListeners(): boolean;
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    get value(): T;
+    set value(value: T);
+    invalidate(): void;
+    get disposed(): boolean;
+    dispose(): void;
+    private notify;
+}
+/**
+ * Returns true if the value is a ObservableValue.
+ * @param value
+ */
+export declare function isObservableValue(value: any): value is ObservableValue<any>;
+/**
+ * Creates a data provider.
+ * @param value
+ */
+export declare function data<T>(value: T): MutableValueImpl<T>;
+/**
+ * If the value is a ObservableValue, returns the data provider as is. Otherwise, wraps the value in
+ * provider.
+ *
+ * @param value
+ */
+export declare function asData<T>(value: MaybeObservableValue<T>): ObservableValue<T>;
+export type OnDataRequested<T> = (setData: (value: T) => void) => Unsubscribe;
+export declare class ExternalMutableValue<T> extends MutableValueBase<T> {
+    private readonly onDataRequested;
+    private _data;
+    private externalDataSub;
+    constructor(currentValue: T, onDataRequested: OnDataRequested<T>);
+    get value(): T;
+    get changeId(): number;
+    set value(_value: T);
+    onData(callback: DataChangedCallback<T>): Unsubscribe;
+    invalidate(): void;
+}
+/**
+ * Creates a data provider that can observe an external event system when onData is called.
+ *
+ * @param initialValue
+ * @param onDataRequested
+ */
+export declare function externalData<T>(initialValue: T, onDataRequested: (setData: (value: T) => void) => Unsubscribe): ObservableValue<T>;
+export {};
+//# sourceMappingURL=observableValue.d.ts.map

package/docs/OBSERVABLE.md

@@ -0,0 +1,95 @@
+# Observable
+
+# ObservableValue\<T>
+
+An `ObservableValue<T>` represents a reactive, read-only data container that can
+be observed for changes over time. It is designed for simple and efficient state
+tracking without introducing third-party reactivity systems.
+
+## Key Features
+
+- Reactive: Subscribers are notified on value changes
+- Composable: You can derive new observable values using `map` and `pick`
+- Typed: Strong type safety for both value and callback arguments
+- Lightweight: Minified and GZipped bundle size is under 1KiB.
+
+## Example
+
+Use `data` to create a MutableValue for a data type.
+
+```typescript
+const user$ = data({ name: 'Alice', age: 30 })
+
+const name$ = user$.pick('name')
+name$.onData((name) => {
+    console.log('Name changed:', name)
+})
+
+user$.value = { name: 'Bob', age: 30 }
+// Logs: "Name changed: Bob"
+
+age$ = user$.pick('age')
+age$.value = 31
+
+user$.value.age // 31
+```
+
+## Utilities
+
+### combineData
+
+Combines multiple data providers into a single record, notifying observers when
+any have changed.
+
+```typescript
+const a = data(1)
+const b = data('x')
+const combined = combineData({ a, b })
+
+combined.onValue((v) => {
+    console.log('changed: ', v.a, v.b)
+})
+
+a.value = 2
+// Logs: "changed: 2 x"
+b.value = 'y'
+// Logs: "changed: 2 y"
+```
+
+Note - combined onValue callback is invoked synchronously; every change from
+every sub-provider will be notified to observers. See `throttle` in vinyl-util
+to handle frequent changes.
+
+## externalData
+
+Creates an `ObservableValue` that integrates with an external data source. The
+data is only actively fetched or listened to when a subscriber calls `onData`,
+allowing lazy subscription to external event systems such as WebSocket, polling,
+or other push-based updates.
+
+Returns An ObservableValue<T> that:
+
+- Emits initialValue immediately on subscription.
+- Receives future values from onDataRequested.
+- Automatically unsubscribes from the external source when no listeners remain.
+
+Example:
+
+```typescript
+import { externalData } from './data'
+
+const timeData = externalData<Date>(new Date(), (setData) => {
+    const interval = setInterval(() => {
+        setData(new Date())
+    }, 1000)
+
+    return () => clearInterval(interval)
+})
+
+const unsubscribe = timeData.onData((now) => {
+    console.log('Current time:', now)
+})
+
+// Later, to stop receiving updates
+unsubscribe()
+```

package/package.json

@@ -0,0 +1,81 @@
+{
+    "name": "@amazon/vinyl-observable",
+    "version": "1.0.0",
+    "description": "A simple active model",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/amazonmusic/vinyl.git"
+    },
+    "license": "UNLICENSED",
+    "module": "./dist/index.js",
+    "main": "./dist/index.cjs",
+    "types": "./dist/types/ts3.7/index.d.ts",
+    "type": "module",
+    "sideEffects": [
+        "test/**/*"
+    ],
+    "files": [
+        "dist/*",
+        "docs/*"
+    ],
+    "typesVersions": {
+        ">=5.4": {
+            "*": [
+                "./dist/types/current/index.d.ts"
+            ]
+        },
+        ">=4.7": {
+            "*": [
+                "./dist/types/ts4.7/index.d.ts"
+            ]
+        },
+        ">=4.1": {
+            "*": [
+                "./dist/types/ts4.1/index.d.ts"
+            ]
+        },
+        ">=3.7": {
+            "*": [
+                "./dist/types/ts3.7/index.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "types@>=5.4": "./dist/types/current/index.d.ts",
+            "types@>=4.7": "./dist/types/ts4.7/index.d.ts",
+            "require": "./dist/index.cjs",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "analyzeExports": "tsx buildSrc/analyzeExports.ts",
+        "analyzeExports:write": "tsx buildSrc/analyzeExports.ts --write",
+        "clean": "rimraf --glob dist .eslintcache \"**/*.tsbuildinfo\"",
+        "indexFiles:check": "tsx buildSrc/writeIndexFiles.ts --check",
+        "indexFiles:write": "tsx buildSrc/writeIndexFiles.ts",
+        "build": "tsx buildSrc/build.ts",
+        "build:release": "tsx buildSrc/build.ts --release",
+        "prettier:check": "prettier . --ignore-path ../../.prettierignore --cache --check",
+        "prettier:write": "prettier . --ignore-path ../../.prettierignore --cache --write",
+        "eslint:check": "eslint . --cache --max-warnings=0",
+        "eslint:write": "eslint . --cache --fix",
+        "lint": "npm run indexFiles:check && npm run eslint:check && npm run prettier:check",
+        "lint:write": "npm run indexFiles:write && npm run eslint:write && npm run prettier:write",
+        "validate": "tsc --project test/unit && npm run lint && npm run test",
+        "test": "tsx --tsconfig ../../tsconfig.flat.json ../../node_modules/jasmine/bin/jasmine --config=test/unit/jasmine.config.json",
+        "test:coverage": "c8 npm run test",
+        "watch": "tsx buildSrc/build.ts --watch",
+        "watch:release": "tsx buildSrc/build.ts --watch --release"
+    },
+    "devDependencies": {
+        "@amazon/vinyl-build-utils": "^1.0.0",
+        "@amazon/vinyl-jasmine-wrapper": "^1.0.0"
+    },
+    "dependencies": {
+        "@amazon/vinyl-util": "^1.0.0"
+    },
+    "browserslist": [
+        "defaults, chrome 52, firefox 54, edge 15, safari 8"
+    ]
+}