@ngstato/core 0.3.0 → 0.4.0

package/README.md

@@ -1,101 +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é)
-```
-
-## 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 |
-|--------|-------------|
-| `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 |
-
-## 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,14 +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 on<S extends object>(sourceAction: Function, handler: (store: S, event?: {
+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;
-}) => void | Promise<void>): () => void;
+};
+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>;
@@ -271,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;
@@ -295,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 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 };
+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 };

package/dist/index.d.ts

@@ -44,14 +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 on<S extends object>(sourceAction: Function, handler: (store: S, event?: {
+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;
-}) => void | Promise<void>): () => void;
+};
+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>;
@@ -271,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;
@@ -295,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 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 };
+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 };