@ngstato/core 0.2.0 → 0.3.0

package/README.md

@@ -40,6 +40,34 @@ console.log(store.users)   // User[]
 console.log(store.total)   // number (selector memoïzé)
 ```
 
+## Réactions inter-stores (`on`)
+
+Écouter la fin d’exécution d’une action précise (success **ou** error) et réagir ailleurs (toast, analytics, déclencher une autre action, etc.).
+
+```ts
+import { createStore, on } from '@ngstato/core'
+
+const userStore = createStore({
+  users: [] as { id: string; name: string }[],
+  actions: {
+    async loadUsers(state) {
+      state.users = await fetch('/api/users').then(r => r.json())
+    }
+  }
+})
+
+const unsubscribe = on(userStore.loadUsers, (_store, event) => {
+  if (event?.status === 'success') {
+    console.log(`[users] loaded in ${event.duration}ms`)
+  } else {
+    console.error('[users] load failed:', event?.error)
+  }
+})
+
+// Plus tard…
+unsubscribe()
+```
+
 ## Helpers
 
 | Helper | Description |
@@ -47,7 +75,17 @@ console.log(store.total)   // number (selector memoïzé)
 | `abortable()` | Annule la requête précédente si l'action est rappelée |
 | `debounced()` | Debounce sans RxJS |
 | `throttled()` | Throttle sans RxJS |
+| `exclusive()` | Ignore les nouveaux appels pendant qu'une exécution est en cours |
 | `retryable()` | Retry avec backoff fixe ou exponentiel |
+| `queued()` | Met en file et exécute les appels dans l'ordre d'arrivée |
+| `distinctUntilChanged()` | Ignore les appels si l’entrée ne change pas |
+| `forkJoin()` | Lance des tâches en parallèle, attend tout |
+| `race()` | Retourne la première tâche terminée |
+| `createEntityAdapter()` | Collections normalisées (ids/entities) + CRUD/selectors |
+| `withEntities()` | Injecte une slice entities + actions/selectors générés |
+| `combineLatest()` | Compose plusieurs deps pour `effects` |
+| `combineLatestStream()` | Combine plusieurs flux externes (compatible RxJS) |
+| `pipeStream()` + operators | Composable streams (`map`, `filter`, `distinctUntilChanged`, `debounce`, `throttle`, `switchMap`, `concatMap`, `exhaustMap`, `mergeMap`, `catchError`, `retry`) |
 | `fromStream()` | Realtime — WebSocket, Firebase, Supabase |
 | `optimistic()` | Optimistic update + rollback automatique |
 | `withPersist()` | Persistance localStorage/sessionStorage + migration |

package/dist/index.d.mts

@@ -45,6 +45,13 @@ declare class StatoHttpError extends Error {
 }
 
 declare function createStore<S extends object>(config: S & StatoStoreConfig<S>): any;
+declare function on<S extends object>(sourceAction: Function, handler: (store: S, event?: {
+    name: string;
+    args: unknown[];
+    status: 'success' | 'error';
+    duration: number;
+    error?: Error;
+}) => void | Promise<void>): () => void;
 
 interface RequestOptions {
     params?: Record<string, string | number | boolean>;
@@ -106,6 +113,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;
@@ -150,4 +300,4 @@ 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 DevToolsState, type EffectDepsFn, type EffectEntry, type EffectRunner, type EntityAdapterOptions, type EntityId, type EntityState, 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, mergeMapStream, on, optimistic, pipeStream, queued, race, retryStream, retryable, switchMapStream, throttleStream, throttled, withEntities, withPersist };

package/dist/index.d.ts

@@ -45,6 +45,13 @@ declare class StatoHttpError extends Error {
 }
 
 declare function createStore<S extends object>(config: S & StatoStoreConfig<S>): any;
+declare function on<S extends object>(sourceAction: Function, handler: (store: S, event?: {
+    name: string;
+    args: unknown[];
+    status: 'success' | 'error';
+    duration: number;
+    error?: Error;
+}) => void | Promise<void>): () => void;
 
 interface RequestOptions {
     params?: Record<string, string | number | boolean>;
@@ -106,6 +113,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;
@@ -150,4 +300,4 @@ 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 DevToolsState, type EffectDepsFn, type EffectEntry, type EffectRunner, type EntityAdapterOptions, type EntityId, type EntityState, 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, mergeMapStream, on, optimistic, pipeStream, queued, race, retryStream, retryable, switchMapStream, throttleStream, throttled, withEntities, withPersist };