@ngstato/core 0.2.0 → 0.4.0

package/README.md

@@ -1,63 +1,163 @@
-# @ngstato/core
-
-State management framework-agnostic — Signals-first, sans RxJS obligatoire.
-
-## Installation
-```bash
-npm install @ngstato/core
-```
-
-## Usage
-```ts
-import { createStore, http } from '@ngstato/core'
-
-const store = createStore({
-  users:     [] as User[],
-  isLoading: false,
-
-  actions: {
-    async loadUsers(state) {
-      state.isLoading = true
-      state.users     = await http.get('/users')
-      state.isLoading = false
-    }
-  },
-
-  selectors: {
-    total: (state) => state.users.length
-  },
-
-  effects: [
-    [
-      (state) => state.users.length,
-      (count) => console.log('Total users:', count)
-    ]
-  ]
-})
-
-await store.loadUsers()
-console.log(store.users)   // User[]
-console.log(store.total)   // number (selector memoïzé)
-```
-
-## Helpers
-
-| Helper | Description |
-|--------|-------------|
-| `abortable()` | Annule la requête précédente si l'action est rappelée |
-| `debounced()` | Debounce sans RxJS |
-| `throttled()` | Throttle sans RxJS |
-| `retryable()` | Retry avec backoff fixe ou exponentiel |
-| `fromStream()` | Realtime — WebSocket, Firebase, Supabase |
-| `optimistic()` | Optimistic update + rollback automatique |
-| `withPersist()` | Persistance localStorage/sessionStorage + migration |
-
-## Nouvautés v0.2
-
-- `selectors` memoïzés (recalcul seulement quand les dépendances changent)
-- `effects` réactifs explicites avec cleanup automatique
-- `withPersist()` pour hydrater/persister le state
-
-## Documentation
-
-Voir [github.com/becher/ngstato](https://github.com/becher/ngstato)
+<div align="center">
+
+# @ngstato/core
+
+### Tired of 14 lines of RxJS for a simple API call?
+
+**Write `async/await`. Get the same result. Ship ~3 KB instead of ~50 KB.**
+
+[![npm](https://img.shields.io/badge/npm-v0.3.0-blue)](https://www.npmjs.com/package/@ngstato/core)
+[![gzip](https://img.shields.io/badge/gzip-~3KB-brightgreen)](#)
+[![tests](https://img.shields.io/badge/tests-136%2B-green)](#)
+[![license](https://img.shields.io/badge/license-MIT-lightgrey)](#)
+
+[Documentation](https://becher.github.io/ngStato/) · [API Reference](https://becher.github.io/ngStato/api/core) · [Helpers](https://becher.github.io/ngStato/api/helpers)
+
+</div>
+
+---
+
+## Before / After
+
+**NgRx** — rxMethod + pipe + tap + switchMap + from + tapResponse + patchState:
+
+```ts
+load: rxMethod<void>(pipe(
+  tap(() => patchState(store, { loading: true })),
+  switchMap(() => from(service.getAll()).pipe(
+    tapResponse({
+      next:  (users) => patchState(store, { users, loading: false }),
+      error: (e)     => patchState(store, { error: e.message })
+    })
+  ))
+))
+```
+
+**ngStato** — async/await:
+
+```ts
+async load(state) {
+  state.loading = true
+  state.users   = await http.get('/users')
+  state.loading = false
+}
+```
+
+---
+
+## Install
+
+```bash
+npm install @ngstato/core
+```
+
+## 30-second example
+
+```ts
+import { createStore } from '@ngstato/core'
+
+const store = createStore({
+  count: 0,
+  
+  selectors: { doubled: (s) => s.count * 2 },
+  
+  actions: {
+    inc(state)                { state.count++ },
+    add(state, n: number)    { state.count += n },
+    async load(state)        { state.count = await fetchCount() }
+  }
+})
+
+await store.inc()
+store.count      // 1
+store.doubled    // 2 (memoized)
+```
+
+## Real-world store
+
+```ts
+import { createStore, http, retryable, optimistic } from '@ngstato/core'
+
+const store = createStore({
+  users:   [] as User[],
+  loading: false,
+  error:   null as string | null,
+
+  selectors: {
+    total:  (s) => s.users.length,
+    admins: (s) => s.users.filter(u => u.role === 'admin')
+  },
+
+  actions: {
+    loadUsers: retryable(async (state) => {
+      state.loading = true
+      state.users   = await http.get('/users')
+      state.loading = false
+    }, { attempts: 3, backoff: 'exponential' }),
+
+    deleteUser: optimistic(
+      (state, id: string) => { state.users = state.users.filter(u => u.id !== id) },
+      async (_, id)       => { await http.delete(`/users/${id}`) }
+    )
+  },
+
+  hooks: {
+    onInit:  (store) => store.loadUsers(),
+    onError: (err, name) => console.error(`[${name}]`, err.message)
+  }
+})
+```
+
+## Concurrency — without RxJS
+
+```ts
+import { exclusive, abortable, queued, retryable, optimistic } from '@ngstato/core'
+
+actions: {
+  submit: exclusive(async (s) => { ... }),             // → exhaustMap
+  search: abortable(async (s, q, { signal }) => { }),  // → switchMap
+  send:   queued(async (s, msg) => { ... }),            // → concatMap
+  load:   retryable(async (s) => { ... }, opts),        // → retryWhen
+  delete: optimistic(apply, confirm),                   // → manual in NgRx
+}
+```
+
+Plus `debounced` · `throttled` · `distinctUntilChanged` · `forkJoin` · `race` · `combineLatest` · `fromStream` · `pipeStream` + 12 stream operators · `createEntityAdapter` · `withEntities` · `withPersist` · `mergeFeatures` · `on()` → [Full API →](https://becher.github.io/ngStato/api/helpers)
+
+## Inter-store reactions
+
+```ts
+import { on } from '@ngstato/core'
+
+on([userStore.create, userStore.delete], (_, event) => {
+  console.log(`${event.name} ${event.status} in ${event.duration}ms`)
+})
+```
+
+## Feature composition
+
+```ts
+const store = createStore({
+  items: [] as Item[],
+  ...mergeFeatures(withLoading(), withPagination()),
+  actions: { async load(state) { ... } }
+})
+// store.loading, store.page, store.hasError — all available
+```
+
+## The numbers
+
+| | NgRx v21 | ngStato |
+|:--|:--|:--|
+| Bundle | ~50 KB | **~3 KB** |
+| CRUD store | ~90 lines | **~45 lines** |
+| Concepts for async | 9 | **1** |
+| RxJS required | Yes | **No** |
+
+## 📖 Documentation
+
+**[becher.github.io/ngStato](https://becher.github.io/ngStato/)** — [Quick start](https://becher.github.io/ngStato/guide/start-in-5-min) · [Core concepts](https://becher.github.io/ngStato/guide/core-concepts) · [API](https://becher.github.io/ngStato/api/core) · [Helpers](https://becher.github.io/ngStato/api/helpers) · [NgRx migration](https://becher.github.io/ngStato/migration/ngrx-to-ngstato)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };