@ngstato/core 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -44,7 +44,17 @@ declare class StatoHttpError extends Error {
     constructor(status: number, body: string);
 }
 
-declare function createStore<S extends object>(config: S & StatoStoreConfig<S>): any;
+declare function createStore<S extends object>(config: S & StatoStoreConfig<S>, __internal?: {
+    skipInit?: boolean;
+}): any;
+type OnEvent = {
+    name: string;
+    args: unknown[];
+    status: 'success' | 'error';
+    duration: number;
+    error?: Error;
+};
+declare function on<S extends object>(sourceAction: Function | Function[], handler: (store: S, event: OnEvent) => void | Promise<void>): () => void;
 
 interface RequestOptions {
     params?: Record<string, string | number | boolean>;
@@ -106,6 +116,149 @@ declare function fromStream<S, T>(setupFn: (state: S) => StatoObservable<T>, upd
 
 declare function optimistic<S, A extends unknown[]>(immediate: (state: S, ...args: A) => void, confirm: (state: S, ...args: A) => Promise<void>): (state: S, ...args: A) => Promise<void>;
 
+declare function exclusive<S, A extends unknown[]>(fn: (state: S, ...args: A) => Promise<void>): (state: S, ...args: A) => Promise<void>;
+
+declare function queued<S, A extends unknown[]>(fn: (state: S, ...args: A) => Promise<void>): (state: S, ...args: A) => Promise<void>;
+
+type Comparator<T> = (prev: T, next: T) => boolean;
+declare function distinctUntilChanged<S, A extends unknown[], K>(fn: (state: S, ...args: A) => void | Promise<void>, keySelector: (...args: A) => K, comparator?: Comparator<K>): (state: S, ...args: A) => Promise<void>;
+
+type TaskContext$1 = {
+    signal: AbortSignal;
+};
+type Task$1<T> = (ctx: TaskContext$1) => Promise<T> | T;
+type ForkJoinOptions = {
+    signal?: AbortSignal;
+};
+declare function forkJoin<T extends Record<string, Task$1<any>>>(tasks: T, options?: ForkJoinOptions): Promise<{
+    [K in keyof T]: Awaited<ReturnType<T[K]>>;
+}>;
+
+type TaskContext = {
+    signal: AbortSignal;
+};
+type Task<T> = (ctx: TaskContext) => Promise<T> | T;
+type RaceOptions = {
+    signal?: AbortSignal;
+};
+declare function race<T>(tasks: Array<Task<T>>, options?: RaceOptions): Promise<T>;
+
+type DepFn<S, T> = (state: S) => T;
+declare function combineLatest<S>(): <T extends unknown[]>(...deps: { [K in keyof T]: DepFn<S, T[K]>; }) => (state: S) => T;
+
+declare function combineLatestStream<T extends unknown[]>(...sources: {
+    [K in keyof T]: StatoObservable<T[K]>;
+}): StatoObservable<T>;
+
+type EntityId = string | number;
+interface EntityState<T> {
+    ids: EntityId[];
+    entities: Record<string, T>;
+}
+type Update<T> = {
+    id: EntityId;
+    changes: Partial<T>;
+};
+type SelectId<T> = (entity: T) => EntityId;
+interface EntityAdapterOptions<T> {
+    selectId?: SelectId<T>;
+    sortComparer?: (a: T, b: T) => number;
+}
+declare function createEntityAdapter<T extends Record<string, any>>(options?: EntityAdapterOptions<T>): {
+    selectId: SelectId<T>;
+    sortComparer: ((a: T, b: T) => number) | undefined;
+    getInitialState: <E extends object = {}>(extra?: E) => EntityState<T> & E;
+    addOne: (entity: T, state: EntityState<T>) => void;
+    addMany: (entities: T[], state: EntityState<T>) => void;
+    setAll: (entities: T[], state: EntityState<T>) => void;
+    upsertOne: (entity: T, state: EntityState<T>) => void;
+    upsertMany: (entities: T[], state: EntityState<T>) => void;
+    updateOne: (update: Update<T>, state: EntityState<T>) => void;
+    removeOne: (id: EntityId, state: EntityState<T>) => void;
+    removeMany: (ids: EntityId[], state: EntityState<T>) => void;
+    removeAll: (state: EntityState<T>) => void;
+    getSelectors: <S = EntityState<T>>(selectState?: (state: S) => EntityState<T>) => {
+        selectIds: (state: S | EntityState<T>) => EntityId[];
+        selectEntities: (state: S | EntityState<T>) => Record<string, T>;
+        selectAll: (state: S | EntityState<T>) => T[];
+        selectTotal: (state: S | EntityState<T>) => number;
+        selectById: (state: S | EntityState<T>, id: EntityId) => T;
+    };
+};
+
+type EntityAdapter<T> = {
+    getInitialState: <E extends object = {}>(extra?: E) => EntityState<T> & E;
+    addOne: (entity: T, state: EntityState<T>) => void;
+    addMany: (entities: T[], state: EntityState<T>) => void;
+    setAll: (entities: T[], state: EntityState<T>) => void;
+    upsertOne: (entity: T, state: EntityState<T>) => void;
+    upsertMany: (entities: T[], state: EntityState<T>) => void;
+    updateOne: (update: Update<T>, state: EntityState<T>) => void;
+    removeOne: (id: EntityId, state: EntityState<T>) => void;
+    removeMany: (ids: EntityId[], state: EntityState<T>) => void;
+    removeAll: (state: EntityState<T>) => void;
+    getSelectors: <S = EntityState<T>>(selectState?: (state: S) => EntityState<T>) => {
+        selectIds: (state: S | EntityState<T>) => EntityId[];
+        selectEntities: (state: S | EntityState<T>) => Record<string, T>;
+        selectAll: (state: S | EntityState<T>) => T[];
+        selectTotal: (state: S | EntityState<T>) => number;
+        selectById: (state: S | EntityState<T>, id: EntityId) => T | undefined;
+    };
+};
+type WithEntitiesSelectorsNames = Partial<{
+    ids: string;
+    entities: string;
+    all: string;
+    total: string;
+    byId: string;
+}>;
+type WithEntitiesActionsNames = Partial<{
+    addOne: string;
+    addMany: string;
+    setAll: string;
+    upsertOne: string;
+    upsertMany: string;
+    updateOne: string;
+    removeOne: string;
+    removeMany: string;
+    removeAll: string;
+}>;
+type WithEntitiesOptions<T> = {
+    key: string;
+    adapter: EntityAdapter<T>;
+    initial?: T[];
+    selectors?: WithEntitiesSelectorsNames;
+    actions?: WithEntitiesActionsNames;
+};
+declare function withEntities<S extends object, T>(config: S & StatoStoreConfig<S>, options: WithEntitiesOptions<T>): S & StatoStoreConfig<S>;
+
+type MaybeObservable<T> = StatoObservable<T> | Promise<T> | T;
+type StreamOperator<I, O> = (source: StatoObservable<I>) => StatoObservable<O>;
+declare function pipeStream<T>(source: StatoObservable<T>): StatoObservable<T>;
+declare function pipeStream<T, A>(source: StatoObservable<T>, op1: StreamOperator<T, A>): StatoObservable<A>;
+declare function pipeStream<T, A, B>(source: StatoObservable<T>, op1: StreamOperator<T, A>, op2: StreamOperator<A, B>): StatoObservable<B>;
+declare function pipeStream<T, A, B, C>(source: StatoObservable<T>, op1: StreamOperator<T, A>, op2: StreamOperator<A, B>, op3: StreamOperator<B, C>): StatoObservable<C>;
+declare function mapStream<I, O>(mapFn: (value: I) => O): StreamOperator<I, O>;
+declare function filterStream<T>(predicate: (value: T) => boolean): StreamOperator<T, T>;
+type Mapper<I, O> = (value: I, ctx: {
+    signal: AbortSignal;
+}) => MaybeObservable<O>;
+declare function switchMapStream<I, O>(mapper: Mapper<I, O>): StreamOperator<I, O>;
+declare function concatMapStream<I, O>(mapper: Mapper<I, O>): StreamOperator<I, O>;
+declare function exhaustMapStream<I, O>(mapper: Mapper<I, O>): StreamOperator<I, O>;
+declare function mergeMapStream<I, O>(mapper: Mapper<I, O>, options?: {
+    concurrency?: number;
+}): StreamOperator<I, O>;
+declare function distinctUntilChangedStream<T, K = T>(keySelector?: (value: T) => K, comparator?: (prev: K, next: K) => boolean): StreamOperator<T, T>;
+declare function debounceStream<T>(ms: number): StreamOperator<T, T>;
+declare function throttleStream<T>(ms: number): StreamOperator<T, T>;
+declare function catchErrorStream<T>(handler: (error: unknown) => MaybeObservable<T>): StreamOperator<T, T>;
+declare function retryStream<T>(options?: {
+    attempts?: number;
+    delay?: number;
+    backoff?: 'fixed' | 'exponential';
+}): StreamOperator<T, T>;
+
 interface PersistStorage {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
@@ -121,21 +274,103 @@ interface PersistOptions<S extends object> {
 }
 declare function withPersist<S extends object>(config: S & StatoStoreConfig<S>, options: PersistOptions<StateSlice<S>>): S & StatoStoreConfig<S>;
 
+interface FeatureConfig {
+    state?: Record<string, unknown>;
+    actions?: Record<string, Function>;
+    computed?: Record<string, Function>;
+    selectors?: Record<string, Function>;
+    effects?: EffectEntry<any>[];
+    hooks?: Partial<StatoHooks<any>>;
+}
+type MergedFeature = {
+    actions?: Record<string, Function>;
+    computed?: Record<string, Function>;
+    selectors?: Record<string, Function>;
+    effects?: EffectEntry<any>[];
+    hooks?: Partial<StatoHooks<any>>;
+    [key: string]: unknown;
+};
+declare function mergeFeatures(...features: FeatureConfig[]): MergedFeature;
+
+/**
+ * withProps() — Attach external properties to a store config.
+ *
+ * Properties are accessible on the store instance but NOT part of the state.
+ * Use this to expose injected services on the store object.
+ *
+ * @example
+ * ```ts
+ * // Pattern 1: Expose services on the store
+ * export const UsersStore = StatoStore(() => {
+ *   const api     = inject(ApiService)
+ *   const notifier = inject(NotificationService)
+ *
+ *   const store = createStore({
+ *     users:   [] as User[],
+ *     loading: false,
+ *
+ *     actions: {
+ *       async loadUsers(state) {
+ *         state.loading = true
+ *         state.users = await api.getUsers()   // closure over injected service
+ *         state.loading = false
+ *       },
+ *
+ *       async deleteUser(state, id: string) {
+ *         await api.deleteUser(id)
+ *         state.users = state.users.filter(u => u.id !== id)
+ *         notifier.success('User deleted')
+ *       }
+ *     }
+ *   })
+ *
+ *   // Attach props to the store — accessible but not in state
+ *   return withProps(store, { api, notifier })
+ * })
+ *
+ * // In a component:
+ * store = injectStore(UsersStore)
+ * store.users()            // Signal<User[]>
+ * store.loadUsers()        // action
+ * store.api                // ApiService — read-only, not in state
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Pattern 2: Configuration props
+ * return withProps(store, {
+ *   storeName: 'Users',
+ *   version:   '1.0.0',
+ *   config:    { pageSize: 20, cacheTTL: 60_000 }
+ * })
+ * ```
+ */
+declare function withProps<S extends object, P extends Record<string, unknown>>(store: S, props: P): S & Readonly<P>;
+
 interface ActionLog {
     id: number;
     name: string;
+    storeName: string;
     args: unknown[];
     duration: number;
     status: 'success' | 'error';
     error?: string;
-    prevState: unknown;
-    nextState: unknown;
+    prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
     at: string;
 }
 interface DevToolsState {
     logs: ActionLog[];
     isOpen: boolean;
     maxLogs: number;
+    activeLogId: number | null;
+    isTimeTraveling: boolean;
+}
+interface DevToolsSnapshot {
+    version: number;
+    timestamp: string;
+    stores: Record<string, unknown>;
+    logs: ActionLog[];
 }
 interface DevToolsInstance {
     state: DevToolsState;
@@ -145,9 +380,21 @@ interface DevToolsInstance {
     close: () => void;
     toggle: () => void;
     subscribe: (cb: (state: DevToolsState) => void) => () => void;
+    travelTo: (logId: number) => void;
+    undo: () => void;
+    redo: () => void;
+    resume: () => void;
+    replay: (logId: number) => void;
+    exportSnapshot: () => DevToolsSnapshot;
+    importSnapshot: (snapshot: DevToolsSnapshot) => void;
+    registerStore: (name: string, publicStore: any, internalStore: any) => void;
+    getStoreRegistry: () => Map<string, {
+        store: any;
+        internalStore: any;
+    }>;
 }
 declare function createDevTools(maxLogs?: number): DevToolsInstance;
 declare const devTools: DevToolsInstance;
 declare function connectDevTools(store: any, storeName: string): void;
 
-export { type ActionLog, type DevToolsInstance, type DevToolsState, type EffectDepsFn, type EffectEntry, type EffectRunner, type PersistOptions, type PersistStorage, type RequestOptions, type StatoConfig, type StatoHooks, StatoHttp, StatoHttpError, type StatoStoreConfig, type StatoStoreInstance, abortable, configureHttp, connectDevTools, createDevTools, createHttp, createStore, debounced, devTools, fromStream, http, optimistic, retryable, throttled, withPersist };
+export { type ActionLog, type DevToolsInstance, type DevToolsSnapshot, type DevToolsState, type EffectDepsFn, type EffectEntry, type EffectRunner, type EntityAdapterOptions, type EntityId, type EntityState, type FeatureConfig, type MergedFeature, type OnEvent, type PersistOptions, type PersistStorage, type RequestOptions, type StatoConfig, type StatoHooks, StatoHttp, StatoHttpError, type StatoStoreConfig, type StatoStoreInstance, type Update, type WithEntitiesOptions, abortable, catchErrorStream, combineLatest, combineLatestStream, concatMapStream, configureHttp, connectDevTools, createDevTools, createEntityAdapter, createHttp, createStore, debounceStream, debounced, devTools, distinctUntilChanged, distinctUntilChangedStream, exclusive, exhaustMapStream, filterStream, forkJoin, fromStream, http, mapStream, mergeFeatures, mergeMapStream, on, optimistic, pipeStream, queued, race, retryStream, retryable, switchMapStream, throttleStream, throttled, withEntities, withPersist, withProps };