@thalesfp/snapstate 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,109 @@
+type AsyncStatusValue = "idle" | "loading" | "ready" | "error";
+interface AsyncStatus {
+    readonly value: AsyncStatusValue;
+    readonly isIdle: boolean;
+    readonly isLoading: boolean;
+    readonly isReady: boolean;
+    readonly isError: boolean;
+}
+declare function asyncStatus(value: AsyncStatusValue): AsyncStatus;
+/** Async operation status and error. Tracks the lifecycle of an `api.fetch`/`api.get`/`api.post` call. */
+interface OperationState {
+    status: AsyncStatus;
+    error: string | null;
+}
+type Listener = () => void;
+type Unsubscribe = () => void;
+type DotPaths<T, Prefix extends string = ""> = T extends object ? {
+    [K in keyof T & string]: `${Prefix}${K}` | DotPaths<T[K], `${Prefix}${K}.`>;
+}[keyof T & string] : never;
+type GetByPath<T, P extends string> = P extends "" ? T : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? GetByPath<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+type ArrayPaths<T> = {
+    [K in keyof T & string]: T[K] extends any[] ? K : never;
+}[keyof T & string];
+type ObjectArrayPaths<T> = {
+    [K in keyof T & string]: T[K] extends (infer V)[] ? V extends Date | RegExp | Map<any, any> | Set<any> | Function | any[] ? never : V extends Record<string, any> ? K : never : never;
+}[keyof T & string];
+type ElementOf<A> = A extends (infer V)[] ? V : never;
+type Updater<V> = V | ((prev: V) => V);
+interface StoreOptions {
+    /** Auto-batch synchronous sets via microtask (default: true) */
+    autoBatch?: boolean;
+}
+/** Handle to a computed (derived) value. Call `get()` to read, `destroy()` to stop tracking. */
+interface ComputedRef<V> {
+    get(): V;
+    destroy(): void;
+}
+/** Options for an HTTP request (method, body, headers). */
+interface HttpRequestInit {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Interface for the HTTP layer used by `api.get` and `api.post/put/patch/delete`. */
+interface HttpClient {
+    request<R = unknown>(url: string, init?: HttpRequestInit): Promise<R>;
+}
+/** Options for HTTP verb methods (`api.post`, `api.put`, etc.). */
+interface ApiRequestOptions<R = unknown> {
+    body?: unknown;
+    headers?: Record<string, string>;
+    onSuccess?: (data: R) => void;
+    onError?: (error: Error) => void;
+}
+interface Subscribable<T extends object> {
+    subscribe(callback: Listener): Unsubscribe;
+    getSnapshot(): T;
+}
+interface StateAccessor<T extends object> {
+    get(): T;
+    get<P extends DotPaths<T>>(path: P): GetByPath<T, P>;
+    set<P extends DotPaths<T>>(path: P, value: Updater<GetByPath<T, P>>): void;
+    batch(fn: () => void): void;
+    computed<V>(deps: (keyof T & string)[], fn: (state: T) => V): ComputedRef<V>;
+    append<P extends ArrayPaths<T>>(path: P, ...items: ElementOf<T[P]>[]): void;
+    prepend<P extends ArrayPaths<T>>(path: P, ...items: ElementOf<T[P]>[]): void;
+    insertAt<P extends ArrayPaths<T>>(path: P, index: number, ...items: ElementOf<T[P]>[]): void;
+    patch<P extends ObjectArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean, updates: Partial<ElementOf<T[P]>>): void;
+    remove<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): void;
+    removeAt<P extends ArrayPaths<T>>(path: P, index: number): void;
+    at<P extends ArrayPaths<T>>(path: P, index: number): ElementOf<T[P]> | undefined;
+    filter<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): ElementOf<T[P]>[];
+    find<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): ElementOf<T[P]> | undefined;
+    findIndexOf<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): number;
+    count<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): number;
+}
+interface ApiAccessor<K extends string> {
+    fetch(key: K, fn: () => Promise<void>): Promise<void>;
+    get<R = unknown>(key: K, url: string, onSuccess?: (data: R) => void): Promise<void>;
+    post<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    put<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    patch<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    delete<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+}
+
+/** Replace the global HTTP client used by `api.get` and `api.post/put/patch/delete`. */
+declare function setHttpClient(client: HttpClient): void;
+/** Set default headers merged into every HTTP request. Per-request headers override defaults. */
+declare function setDefaultHeaders(headers: Record<string, string>): void;
+declare class SnapStore<T extends object, K extends string = string> {
+    private _store;
+    private _operations;
+    private _generations;
+    protected readonly state: StateAccessor<T>;
+    protected readonly api: ApiAccessor<K>;
+    constructor(initialState: T, options?: StoreOptions);
+    /** Subscribe to all state changes. Returns an unsubscribe function. */
+    subscribe(callback: Listener): Unsubscribe;
+    /** Subscribe to changes at a specific dot-separated path. */
+    subscribe(path: string, callback: Listener): Unsubscribe;
+    /** Return a snapshot of the current state. Compatible with React's `useSyncExternalStore`. */
+    getSnapshot: () => T;
+    /** Get the async status of an operation by key. Returns `idle` if never started. */
+    getStatus(key: K): OperationState;
+    /** Tear down subscriptions and cleanup. */
+    destroy(): void;
+}
+
+export { type AsyncStatus, type AsyncStatusValue, type ComputedRef, type HttpClient, type Listener, SnapStore, type StoreOptions, type Subscribable, type Unsubscribe, asyncStatus, setDefaultHeaders, setHttpClient };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+type AsyncStatusValue = "idle" | "loading" | "ready" | "error";
+interface AsyncStatus {
+    readonly value: AsyncStatusValue;
+    readonly isIdle: boolean;
+    readonly isLoading: boolean;
+    readonly isReady: boolean;
+    readonly isError: boolean;
+}
+declare function asyncStatus(value: AsyncStatusValue): AsyncStatus;
+/** Async operation status and error. Tracks the lifecycle of an `api.fetch`/`api.get`/`api.post` call. */
+interface OperationState {
+    status: AsyncStatus;
+    error: string | null;
+}
+type Listener = () => void;
+type Unsubscribe = () => void;
+type DotPaths<T, Prefix extends string = ""> = T extends object ? {
+    [K in keyof T & string]: `${Prefix}${K}` | DotPaths<T[K], `${Prefix}${K}.`>;
+}[keyof T & string] : never;
+type GetByPath<T, P extends string> = P extends "" ? T : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? GetByPath<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+type ArrayPaths<T> = {
+    [K in keyof T & string]: T[K] extends any[] ? K : never;
+}[keyof T & string];
+type ObjectArrayPaths<T> = {
+    [K in keyof T & string]: T[K] extends (infer V)[] ? V extends Date | RegExp | Map<any, any> | Set<any> | Function | any[] ? never : V extends Record<string, any> ? K : never : never;
+}[keyof T & string];
+type ElementOf<A> = A extends (infer V)[] ? V : never;
+type Updater<V> = V | ((prev: V) => V);
+interface StoreOptions {
+    /** Auto-batch synchronous sets via microtask (default: true) */
+    autoBatch?: boolean;
+}
+/** Handle to a computed (derived) value. Call `get()` to read, `destroy()` to stop tracking. */
+interface ComputedRef<V> {
+    get(): V;
+    destroy(): void;
+}
+/** Options for an HTTP request (method, body, headers). */
+interface HttpRequestInit {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Interface for the HTTP layer used by `api.get` and `api.post/put/patch/delete`. */
+interface HttpClient {
+    request<R = unknown>(url: string, init?: HttpRequestInit): Promise<R>;
+}
+/** Options for HTTP verb methods (`api.post`, `api.put`, etc.). */
+interface ApiRequestOptions<R = unknown> {
+    body?: unknown;
+    headers?: Record<string, string>;
+    onSuccess?: (data: R) => void;
+    onError?: (error: Error) => void;
+}
+interface Subscribable<T extends object> {
+    subscribe(callback: Listener): Unsubscribe;
+    getSnapshot(): T;
+}
+interface StateAccessor<T extends object> {
+    get(): T;
+    get<P extends DotPaths<T>>(path: P): GetByPath<T, P>;
+    set<P extends DotPaths<T>>(path: P, value: Updater<GetByPath<T, P>>): void;
+    batch(fn: () => void): void;
+    computed<V>(deps: (keyof T & string)[], fn: (state: T) => V): ComputedRef<V>;
+    append<P extends ArrayPaths<T>>(path: P, ...items: ElementOf<T[P]>[]): void;
+    prepend<P extends ArrayPaths<T>>(path: P, ...items: ElementOf<T[P]>[]): void;
+    insertAt<P extends ArrayPaths<T>>(path: P, index: number, ...items: ElementOf<T[P]>[]): void;
+    patch<P extends ObjectArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean, updates: Partial<ElementOf<T[P]>>): void;
+    remove<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): void;
+    removeAt<P extends ArrayPaths<T>>(path: P, index: number): void;
+    at<P extends ArrayPaths<T>>(path: P, index: number): ElementOf<T[P]> | undefined;
+    filter<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): ElementOf<T[P]>[];
+    find<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): ElementOf<T[P]> | undefined;
+    findIndexOf<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): number;
+    count<P extends ArrayPaths<T>>(path: P, predicate: (item: ElementOf<T[P]>) => boolean): number;
+}
+interface ApiAccessor<K extends string> {
+    fetch(key: K, fn: () => Promise<void>): Promise<void>;
+    get<R = unknown>(key: K, url: string, onSuccess?: (data: R) => void): Promise<void>;
+    post<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    put<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    patch<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+    delete<R = unknown>(key: K, url: string, options?: ApiRequestOptions<R>): Promise<void>;
+}
+
+/** Replace the global HTTP client used by `api.get` and `api.post/put/patch/delete`. */
+declare function setHttpClient(client: HttpClient): void;
+/** Set default headers merged into every HTTP request. Per-request headers override defaults. */
+declare function setDefaultHeaders(headers: Record<string, string>): void;
+declare class SnapStore<T extends object, K extends string = string> {
+    private _store;
+    private _operations;
+    private _generations;
+    protected readonly state: StateAccessor<T>;
+    protected readonly api: ApiAccessor<K>;
+    constructor(initialState: T, options?: StoreOptions);
+    /** Subscribe to all state changes. Returns an unsubscribe function. */
+    subscribe(callback: Listener): Unsubscribe;
+    /** Subscribe to changes at a specific dot-separated path. */
+    subscribe(path: string, callback: Listener): Unsubscribe;
+    /** Return a snapshot of the current state. Compatible with React's `useSyncExternalStore`. */
+    getSnapshot: () => T;
+    /** Get the async status of an operation by key. Returns `idle` if never started. */
+    getStatus(key: K): OperationState;
+    /** Tear down subscriptions and cleanup. */
+    destroy(): void;
+}
+
+export { type AsyncStatus, type AsyncStatusValue, type ComputedRef, type HttpClient, type Listener, SnapStore, type StoreOptions, type Subscribable, type Unsubscribe, asyncStatus, setDefaultHeaders, setHttpClient };