@montra-interactive/deepstate 0.1.0

package/dist/deepstate.d.ts

@@ -0,0 +1,189 @@
+/**
+ * deepstate v2 - Nested BehaviorSubjects Architecture
+ *
+ * Each property has its own observable that emits standalone.
+ * Parent notifications flow upward automatically via RxJS subscriptions.
+ * Siblings are never notified.
+ *
+ * Architecture:
+ * - Leaves (primitives): BehaviorSubject is source of truth
+ * - Objects: combineLatest(children) derives the observable, children are source of truth
+ * - Arrays: BehaviorSubject<T[]> is source of truth, children are projections
+ */
+import { Observable, Subscription } from "rxjs";
+export declare let distinctCallCount: number;
+export declare function resetDistinctCallCount(): void;
+type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+type NonNullablePart<T> = T extends null | undefined ? never : T;
+type HasNull<T> = null extends T ? true : false;
+type HasUndefined<T> = undefined extends T ? true : false;
+type IsNullish<T> = HasNull<T> extends true ? true : HasUndefined<T>;
+type NonNullPartIsObject<T> = NonNullablePart<T> extends object ? NonNullablePart<T> extends Array<unknown> ? false : true : false;
+type IsNullableObject<T> = IsNullish<T> extends true ? NonNullPartIsObject<T> : false;
+/**
+ * Deep readonly type - makes all nested properties readonly.
+ * Used for return types of get() and subscribe() to prevent accidental mutations.
+ */
+export type DeepReadonly<T> = [T] extends [Primitive] ? T : [T] extends [Array<infer U>] ? ReadonlyArray<DeepReadonly<U>> : [T] extends [object] ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * A mutable draft of state T for use in update callbacks.
+ */
+export type Draft<T> = T;
+interface NodeCore<T> {
+    readonly $: Observable<T>;
+    get(): T;
+    set(value: T): void;
+    subscribeOnce?(callback: (value: T) => void): Subscription;
+}
+declare const NODE: unique symbol;
+type RxLeaf<T> = Observable<DeepReadonly<T>> & {
+    /** Get current value synchronously */
+    get(): DeepReadonly<T>;
+    /** Set value */
+    set(value: T): void;
+    /** Subscribe to a single emission, then automatically unsubscribe */
+    subscribeOnce(callback: (value: DeepReadonly<T>) => void): Subscription;
+    [NODE]: NodeCore<T>;
+};
+type RxObject<T extends object> = {
+    [K in keyof T]: RxNodeFor<T[K]>;
+} & Observable<DeepReadonly<T>> & {
+    /** Get current value synchronously */
+    get(): DeepReadonly<T>;
+    /** Set value */
+    set(value: T): void;
+    /**
+     * Update multiple properties in a single emission.
+     * The callback receives the reactive state object - use .set() on properties to update them.
+     * All changes are batched into a single emission.
+     * @example
+     * store.user.update(draft => {
+     *   draft.name.set("Bob");
+     *   draft.age.set(31);
+     * });
+     */
+    update(callback: (draft: RxObject<T>) => void): DeepReadonly<T>;
+    /** Subscribe to a single emission, then automatically unsubscribe */
+    subscribeOnce(callback: (value: DeepReadonly<T>) => void): Subscription;
+    [NODE]: NodeCore<T>;
+};
+type RxArray<T> = Observable<DeepReadonly<T[]>> & {
+    /** Get current value synchronously */
+    get(): DeepReadonly<T[]>;
+    /** Set value */
+    set(value: T[]): void;
+    /**
+     * Update array in a single emission.
+     * The callback receives the reactive array - use .at(), .push(), .pop() etc to update.
+     * All changes are batched into a single emission.
+     * @example
+     * store.items.update(draft => {
+     *   draft.at(0)?.name.set("Updated");
+     *   draft.push({ id: 2, name: "New" });
+     * });
+     */
+    update(callback: (draft: RxArray<T>) => void): DeepReadonly<T[]>;
+    /** Subscribe to a single emission, then automatically unsubscribe */
+    subscribeOnce(callback: (value: DeepReadonly<T[]>) => void): Subscription;
+    /** Get reactive node for array element at index */
+    at(index: number): RxNodeFor<T> | undefined;
+    /** Get current length (also observable) */
+    length: Observable<number> & {
+        get(): number;
+    };
+    /** Push items and return new length */
+    push(...items: T[]): number;
+    /** Pop last item */
+    pop(): DeepReadonly<T> | undefined;
+    /** Map over current values (non-reactive, use .subscribe for reactive) */
+    map<U>(fn: (item: DeepReadonly<T>, index: number) => U): U[];
+    /** Filter current values */
+    filter(fn: (item: DeepReadonly<T>, index: number) => boolean): DeepReadonly<T>[];
+    [NODE]: NodeCore<T[]>;
+};
+/**
+ * RxNullable - For properties typed as `{ ... } | null` or `{ ... } | undefined`
+ *
+ * The node is always present at runtime, enabling deep subscription:
+ * - You can subscribe to `store.user.name` even when `user` is null
+ * - The subscription will emit `undefined` while user is null
+ * - Once user is set to an object, the subscription will emit the actual name value
+ *
+ * @example
+ * const store = state<{ user: { name: string } | null }>({ user: null });
+ *
+ * // Deep subscription works even when user is null
+ * store.user.name.subscribe(name => {
+ *   console.log(name); // undefined when user is null, actual value when set
+ * });
+ *
+ * store.user.get();                    // null
+ * store.user.set({ name: "Alice" });   // Now name subscription emits "Alice"
+ * store.user.name.get();               // "Alice"
+ * store.user.name.set("Bob");          // Works!
+ */
+type RxNullable<T, TNonNull extends object = NonNullablePart<T> & object> = Observable<DeepReadonly<T>> & {
+    /** Get current value (may be null/undefined) */
+    get(): DeepReadonly<T>;
+    /** Set value (can be null/undefined or the full object) */
+    set(value: T): void;
+    /** Subscribe to a single emission, then automatically unsubscribe */
+    subscribeOnce(callback: (value: DeepReadonly<T>) => void): Subscription;
+    /**
+     * Update multiple properties in a single emission.
+     * @example
+     * store.user.update(user => {
+     *   user.name.set("Bob");
+     *   user.age.set(31);
+     * });
+     */
+    update(callback: (draft: RxObject<TNonNull>) => void): DeepReadonly<T>;
+    [NODE]: NodeCore<T>;
+} & {
+    [K in keyof TNonNull]: RxNullableChild<TNonNull[K]>;
+};
+/**
+ * Type for children of a nullable object.
+ * Children are wrapped to handle the case where parent is null:
+ * - When parent is null: get() returns undefined, subscribe emits undefined
+ * - When parent has value: behaves like normal RxNodeFor
+ */
+type RxNullableChild<T> = IsNullableObject<T> extends true ? RxNullable<T> : [T] extends [Primitive] ? RxLeaf<T | undefined> : [T] extends [Array<infer U>] ? RxArray<U> | RxLeaf<undefined> : [T] extends [object] ? RxNullableChildObject<T> : RxLeaf<T | undefined>;
+/**
+ * Type for object children under a nullable parent.
+ * The object itself might be undefined (if parent is null), but if present
+ * it has all the normal object methods and children.
+ */
+type RxNullableChildObject<T extends object> = Observable<DeepReadonly<T> | undefined> & {
+    get(): DeepReadonly<T> | undefined;
+    set(value: T): void;
+    subscribeOnce(callback: (value: DeepReadonly<T> | undefined) => void): Subscription;
+    [NODE]: NodeCore<T | undefined>;
+} & {
+    [K in keyof T]: RxNullableChild<T[K]>;
+};
+type RxNodeFor<T> = IsNullableObject<T> extends true ? RxNullable<T> : [T] extends [Primitive] ? RxLeaf<T> : [T] extends [Array<infer U>] ? RxArray<U> : [T] extends [object] ? RxObject<T> : RxLeaf<T>;
+export type RxState<T extends object> = RxObject<T>;
+export declare function state<T extends object>(initialState: T): RxState<T>;
+/**
+ * Marks a value as nullable, allowing it to transition between null and object.
+ * Use this when you want to start with an object value but later set it to null.
+ *
+ * @example
+ * const store = state({
+ *   // Can start with object and later be set to null
+ *   user: nullable({ name: "Alice", age: 30 }),
+ *   // Can start with null and later be set to object
+ *   profile: nullable<{ bio: string }>(null),
+ * });
+ *
+ * // Use ?. on the nullable property, then access children directly
+ * store.user?.set(null);  // Works!
+ * store.user?.set({ name: "Bob", age: 25 });  // Works!
+ * store.user?.name.set("Charlie");  // After ?. on user, children are directly accessible
+ */
+export declare function nullable<T extends object>(value: T | null): T | null;
+export {};
+//# sourceMappingURL=deepstate.d.ts.map

package/dist/deepstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepstate.d.ts","sourceRoot":"","sources":["../src/deepstate.ts"],"names":[],"mappings":"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"}