redux-sparse-kit 0.0.0-stage → 0.1.0

package/dist/sparseEnhancer-CIcdhh-P.d.mts

@@ -0,0 +1,212 @@
+import { Action, Reducer, StoreEnhancer } from "redux";
+//#region src/segment.d.ts
+/**
+ * The state that is always present in the store, outside of any segment.
+ * Register it once so that segment epics can read it:
+ *
+ * ```ts
+ * declare module 'redux-sparse-kit' {
+ *   interface StaticState extends RootStaticState {}
+ * }
+ * ```
+ */
+interface StaticState {}
+/**
+ * What an idle segment (one no longer held by anything) does until it is
+ * evicted:
+ * - `keep-running` - its reducer and epics keep running, so its state stays
+ *   current.
+ * - `pause-epics` - its reducer keeps running, its epics are stopped and
+ *   started again when the segment is held again.
+ * - `freeze` - its epics are stopped and its reducer is skipped, so its state
+ *   is kept exactly as it was.
+ */
+type WhileIdle = "keep-running" | "pause-epics" | "freeze";
+/**
+ * An epic as far as the core is concerned: a function the epic runner starts.
+ * The `redux-sparse-kit/observable` entry point runs redux-observable epics.
+ */
+type SegmentEpic = (...args: any[]) => unknown;
+/**
+ * A reducer, the epics that drive it and the segments it depends on, injected
+ * together and evicted together. Its `State` is `never` when it has no
+ * reducer: it then owns no slice of the state.
+ */
+interface Segment<Key extends string = string, State = any, Deps extends readonly AnySegment[] = readonly AnySegment[]> {
+  /**
+   * Names the segment, and is the top-level key of the state its reducer
+   * owns when it has one.
+   */
+  readonly key: Key;
+  readonly reducer: unknown extends State ? Reducer<any> | undefined : [State] extends [never] ? undefined : Reducer<State>;
+  /** Segments that must be present for as long as this one is. */
+  readonly deps: Deps;
+  readonly epics: readonly SegmentEpic[];
+  /** Overrides the store's idle timeout for this segment, in milliseconds. */
+  readonly idleTimeout: number | undefined;
+  /** Overrides the store's idle behaviour for this segment. */
+  readonly whileIdle: WhileIdle | undefined;
+}
+/**
+ * Any segment, with or without a reducer. Spelled out rather than written as
+ * `Segment<string, any>`, which a segment without a reducer would not match.
+ */
+interface AnySegment {
+  readonly key: string;
+  readonly reducer: Reducer<any> | undefined;
+  readonly deps: readonly AnySegment[];
+  readonly epics: readonly SegmentEpic[];
+  readonly idleTimeout: number | undefined;
+  readonly whileIdle: WhileIdle | undefined;
+}
+type SliceKeyOf<S> = S extends Segment<infer Key, infer State, any> ? ([State] extends [never] ? never : Key) : never;
+/**
+ * The state slice each of the given segments contributes to the store;
+ * segments without a reducer contribute none.
+ */
+type StateOfSegments<Segments extends AnySegment> = { [S in Segments as SliceKeyOf<S>]: S extends Segment<string, infer State, any> ? State : never; };
+type OwnSliceOf<Key extends string, State> = [State] extends [never] ? {} : { [K in Key]: State; };
+/**
+ * The state a segment may read: the static state, its own slice and the
+ * slices of its direct dependencies.
+ */
+type ScopeStateOf<S extends AnySegment> = StaticState & StateOfSegments<S | S["deps"][number]>;
+type EpicStateOf<Epic> = Epic extends ((action$: any, state$: infer State$, ...rest: any[]) => any) ? State$ extends {
+  readonly value: infer State;
+} ? State : unknown : unknown;
+declare const segmentEpicError: unique symbol;
+/**
+ * Shown when an epic declares a state the segment cannot guarantee: it reads
+ * a segment that is neither the segment itself nor one of its dependencies.
+ */
+interface SegmentEpicStateError<Readable, Declared> {
+  readonly [segmentEpicError]: "The epic reads state outside the segment and its deps";
+  readonly readable: Readable;
+  readonly declared: Declared;
+}
+/** An epic typed with a `void`, `unknown` or `any` state does not read it. */
+type ReadsState<State> = [State] extends [void] ? false : unknown extends State ? false : true;
+type ValidateEpics<Epics extends readonly unknown[], Scope> = { [I in keyof Epics]: ReadsState<EpicStateOf<Epics[I]>> extends false ? unknown : Scope extends EpicStateOf<Epics[I]> ? unknown : SegmentEpicStateError<Scope, EpicStateOf<Epics[I]>>; };
+interface SegmentOptions<Key extends string, State, Deps extends readonly AnySegment[], Epics extends readonly SegmentEpic[]> {
+  key: Key;
+  /** Omitted for a segment that only runs epics or only bundles its deps. */
+  reducer?: Reducer<State>;
+  deps?: Deps;
+  epics?: Epics & ValidateEpics<Epics, StaticState & StateOfSegments<Deps[number]> & OwnSliceOf<Key, State>>;
+  idleTimeout?: number;
+  whileIdle?: WhileIdle;
+}
+/**
+ * Whether a segment with a reducer has been defined under this key. Lets dev
+ * checks tell a read of a segment's slice from a read of static state.
+ */
+declare const isSegmentKey: (key: string) => boolean;
+/**
+ * Defines a segment: a reducer, the epics that drive it and the segments it
+ * depends on, injected together and evicted together. Each part is optional.
+ *
+ * A dependency has to be defined before the segment that lists it, so the
+ * dependency graph cannot contain a cycle.
+ */
+declare function defineSegment<const Key extends string, State = never, const Deps extends readonly AnySegment[] = [], const Epics extends readonly SegmentEpic[] = []>(options: SegmentOptions<Key, State, Deps, Epics>): Segment<Key, State, Deps>;
+//#endregion
+//#region src/sparseEnhancer.d.ts
+/**
+ * Actions the sparse store dispatches. Reducers outside the segments can
+ * handle {@linkcode SparseActionTypes.EVICT} to drop data that refers to an
+ * evicted segment.
+ */
+declare const SparseActionTypes: {
+  /** Segment slices with the keys in `payload.keys` were added to the state. */
+  readonly INJECT: "@@sparse/INJECT";
+  /** Segment slices with the keys in `payload.keys` are removed by this action. */
+  readonly EVICT: "@@sparse/EVICT";
+};
+interface SparseAction extends Action<(typeof SparseActionTypes)[keyof typeof SparseActionTypes]> {
+  payload: {
+    keys: readonly string[];
+  };
+}
+type SparseEvent = {
+  type: "inject";
+  keys: readonly string[];
+} | {
+  type: "evict";
+  keys: readonly string[];
+} | {
+  type: "idle";
+  key: string;
+} | {
+  type: "revive";
+  key: string;
+};
+interface SparseStats {
+  /** Keys of present segments that something holds. */
+  active: string[];
+  /** Keys of present segments waiting for their idle timeout. */
+  idle: string[];
+}
+interface SparseController {
+  /**
+   * Holds the given segments, injecting the ones that are not present yet
+   * together with their dependencies. Returns a function that releases the
+   * hold; calling it more than once has no further effect.
+   */
+  acquire(...segments: readonly AnySegment[]): () => void;
+  /** Whether a segment with this key is present in the store. */
+  has(segmentOrKey: AnySegment | string): boolean;
+  /**
+   * Runs `fn`, deferring injections and evictions it causes until it returns,
+   * so that they reach the store as a single action of each kind.
+   */
+  batch<T>(fn: () => T): T;
+  /** Listens to segments being injected, going idle, revived and evicted. */
+  subscribe(listener: (event: SparseEvent) => void): () => void;
+  /** The keys of the present segments, by state. */
+  stats(): SparseStats;
+}
+interface SparseStoreExt {
+  readonly sparse: SparseController;
+}
+/**
+ * Starts segment epics. `redux-sparse-kit/observable` provides one for
+ * redux-observable.
+ */
+interface EpicRunner {
+  /** Starts `epic` and returns a function that stops it. */
+  run(epic: SegmentEpic, segment: AnySegment): () => void;
+}
+interface SparseOptions {
+  /** Required as soon as a held segment has epics. */
+  epicRunner?: EpicRunner;
+  /**
+   * How long a segment nothing holds stays present before it is evicted, in
+   * milliseconds. `0` evicts it right away, `Infinity` never. Segments can
+   * override it. Defaults to one minute.
+   */
+  idleTimeout?: number;
+  /**
+   * What an idle segment does until it is evicted. Segments can override it.
+   * Defaults to `keep-running`.
+   */
+  whileIdle?: WhileIdle;
+  /**
+   * How many idle segments may wait for their idle timeout at once. Past it,
+   * the ones idle the longest are evicted right away. Defaults to `Infinity`.
+   */
+  maxIdle?: number;
+  /**
+   * Stops the idle clock while the page is hidden, so that time spent in a
+   * background tab does not count towards the idle timeout. Defaults to `true`.
+   */
+  pauseWhenHidden?: boolean;
+}
+/**
+ * A store enhancer that lets segments be injected into and evicted from a
+ * running store. The root reducer passed to `createStore` keeps owning the
+ * static state; segment slices live next to it under their keys.
+ */
+declare function sparseEnhancer(options?: SparseOptions): StoreEnhancer<SparseStoreExt>;
+//#endregion
+export { StaticState as _, SparseEvent as a, isSegmentKey as b, SparseStoreExt as c, ScopeStateOf as d, Segment as f, StateOfSegments as g, SegmentOptions as h, SparseController as i, sparseEnhancer as l, SegmentEpicStateError as m, SparseAction as n, SparseOptions as o, SegmentEpic as p, SparseActionTypes as r, SparseStats as s, EpicRunner as t, AnySegment as u, WhileIdle as v, defineSegment as y };
+//# sourceMappingURL=sparseEnhancer-CIcdhh-P.d.mts.map

package/dist/sparseEnhancer-CIcdhh-P.d.ts

@@ -0,0 +1,212 @@
+import { Action, Reducer, StoreEnhancer } from "redux";
+//#region src/segment.d.ts
+/**
+ * The state that is always present in the store, outside of any segment.
+ * Register it once so that segment epics can read it:
+ *
+ * ```ts
+ * declare module 'redux-sparse-kit' {
+ *   interface StaticState extends RootStaticState {}
+ * }
+ * ```
+ */
+interface StaticState {}
+/**
+ * What an idle segment (one no longer held by anything) does until it is
+ * evicted:
+ * - `keep-running` - its reducer and epics keep running, so its state stays
+ *   current.
+ * - `pause-epics` - its reducer keeps running, its epics are stopped and
+ *   started again when the segment is held again.
+ * - `freeze` - its epics are stopped and its reducer is skipped, so its state
+ *   is kept exactly as it was.
+ */
+type WhileIdle = "keep-running" | "pause-epics" | "freeze";
+/**
+ * An epic as far as the core is concerned: a function the epic runner starts.
+ * The `redux-sparse-kit/observable` entry point runs redux-observable epics.
+ */
+type SegmentEpic = (...args: any[]) => unknown;
+/**
+ * A reducer, the epics that drive it and the segments it depends on, injected
+ * together and evicted together. Its `State` is `never` when it has no
+ * reducer: it then owns no slice of the state.
+ */
+interface Segment<Key extends string = string, State = any, Deps extends readonly AnySegment[] = readonly AnySegment[]> {
+  /**
+   * Names the segment, and is the top-level key of the state its reducer
+   * owns when it has one.
+   */
+  readonly key: Key;
+  readonly reducer: unknown extends State ? Reducer<any> | undefined : [State] extends [never] ? undefined : Reducer<State>;
+  /** Segments that must be present for as long as this one is. */
+  readonly deps: Deps;
+  readonly epics: readonly SegmentEpic[];
+  /** Overrides the store's idle timeout for this segment, in milliseconds. */
+  readonly idleTimeout: number | undefined;
+  /** Overrides the store's idle behaviour for this segment. */
+  readonly whileIdle: WhileIdle | undefined;
+}
+/**
+ * Any segment, with or without a reducer. Spelled out rather than written as
+ * `Segment<string, any>`, which a segment without a reducer would not match.
+ */
+interface AnySegment {
+  readonly key: string;
+  readonly reducer: Reducer<any> | undefined;
+  readonly deps: readonly AnySegment[];
+  readonly epics: readonly SegmentEpic[];
+  readonly idleTimeout: number | undefined;
+  readonly whileIdle: WhileIdle | undefined;
+}
+type SliceKeyOf<S> = S extends Segment<infer Key, infer State, any> ? ([State] extends [never] ? never : Key) : never;
+/**
+ * The state slice each of the given segments contributes to the store;
+ * segments without a reducer contribute none.
+ */
+type StateOfSegments<Segments extends AnySegment> = { [S in Segments as SliceKeyOf<S>]: S extends Segment<string, infer State, any> ? State : never; };
+type OwnSliceOf<Key extends string, State> = [State] extends [never] ? {} : { [K in Key]: State; };
+/**
+ * The state a segment may read: the static state, its own slice and the
+ * slices of its direct dependencies.
+ */
+type ScopeStateOf<S extends AnySegment> = StaticState & StateOfSegments<S | S["deps"][number]>;
+type EpicStateOf<Epic> = Epic extends ((action$: any, state$: infer State$, ...rest: any[]) => any) ? State$ extends {
+  readonly value: infer State;
+} ? State : unknown : unknown;
+declare const segmentEpicError: unique symbol;
+/**
+ * Shown when an epic declares a state the segment cannot guarantee: it reads
+ * a segment that is neither the segment itself nor one of its dependencies.
+ */
+interface SegmentEpicStateError<Readable, Declared> {
+  readonly [segmentEpicError]: "The epic reads state outside the segment and its deps";
+  readonly readable: Readable;
+  readonly declared: Declared;
+}
+/** An epic typed with a `void`, `unknown` or `any` state does not read it. */
+type ReadsState<State> = [State] extends [void] ? false : unknown extends State ? false : true;
+type ValidateEpics<Epics extends readonly unknown[], Scope> = { [I in keyof Epics]: ReadsState<EpicStateOf<Epics[I]>> extends false ? unknown : Scope extends EpicStateOf<Epics[I]> ? unknown : SegmentEpicStateError<Scope, EpicStateOf<Epics[I]>>; };
+interface SegmentOptions<Key extends string, State, Deps extends readonly AnySegment[], Epics extends readonly SegmentEpic[]> {
+  key: Key;
+  /** Omitted for a segment that only runs epics or only bundles its deps. */
+  reducer?: Reducer<State>;
+  deps?: Deps;
+  epics?: Epics & ValidateEpics<Epics, StaticState & StateOfSegments<Deps[number]> & OwnSliceOf<Key, State>>;
+  idleTimeout?: number;
+  whileIdle?: WhileIdle;
+}
+/**
+ * Whether a segment with a reducer has been defined under this key. Lets dev
+ * checks tell a read of a segment's slice from a read of static state.
+ */
+declare const isSegmentKey: (key: string) => boolean;
+/**
+ * Defines a segment: a reducer, the epics that drive it and the segments it
+ * depends on, injected together and evicted together. Each part is optional.
+ *
+ * A dependency has to be defined before the segment that lists it, so the
+ * dependency graph cannot contain a cycle.
+ */
+declare function defineSegment<const Key extends string, State = never, const Deps extends readonly AnySegment[] = [], const Epics extends readonly SegmentEpic[] = []>(options: SegmentOptions<Key, State, Deps, Epics>): Segment<Key, State, Deps>;
+//#endregion
+//#region src/sparseEnhancer.d.ts
+/**
+ * Actions the sparse store dispatches. Reducers outside the segments can
+ * handle {@linkcode SparseActionTypes.EVICT} to drop data that refers to an
+ * evicted segment.
+ */
+declare const SparseActionTypes: {
+  /** Segment slices with the keys in `payload.keys` were added to the state. */
+  readonly INJECT: "@@sparse/INJECT";
+  /** Segment slices with the keys in `payload.keys` are removed by this action. */
+  readonly EVICT: "@@sparse/EVICT";
+};
+interface SparseAction extends Action<(typeof SparseActionTypes)[keyof typeof SparseActionTypes]> {
+  payload: {
+    keys: readonly string[];
+  };
+}
+type SparseEvent = {
+  type: "inject";
+  keys: readonly string[];
+} | {
+  type: "evict";
+  keys: readonly string[];
+} | {
+  type: "idle";
+  key: string;
+} | {
+  type: "revive";
+  key: string;
+};
+interface SparseStats {
+  /** Keys of present segments that something holds. */
+  active: string[];
+  /** Keys of present segments waiting for their idle timeout. */
+  idle: string[];
+}
+interface SparseController {
+  /**
+   * Holds the given segments, injecting the ones that are not present yet
+   * together with their dependencies. Returns a function that releases the
+   * hold; calling it more than once has no further effect.
+   */
+  acquire(...segments: readonly AnySegment[]): () => void;
+  /** Whether a segment with this key is present in the store. */
+  has(segmentOrKey: AnySegment | string): boolean;
+  /**
+   * Runs `fn`, deferring injections and evictions it causes until it returns,
+   * so that they reach the store as a single action of each kind.
+   */
+  batch<T>(fn: () => T): T;
+  /** Listens to segments being injected, going idle, revived and evicted. */
+  subscribe(listener: (event: SparseEvent) => void): () => void;
+  /** The keys of the present segments, by state. */
+  stats(): SparseStats;
+}
+interface SparseStoreExt {
+  readonly sparse: SparseController;
+}
+/**
+ * Starts segment epics. `redux-sparse-kit/observable` provides one for
+ * redux-observable.
+ */
+interface EpicRunner {
+  /** Starts `epic` and returns a function that stops it. */
+  run(epic: SegmentEpic, segment: AnySegment): () => void;
+}
+interface SparseOptions {
+  /** Required as soon as a held segment has epics. */
+  epicRunner?: EpicRunner;
+  /**
+   * How long a segment nothing holds stays present before it is evicted, in
+   * milliseconds. `0` evicts it right away, `Infinity` never. Segments can
+   * override it. Defaults to one minute.
+   */
+  idleTimeout?: number;
+  /**
+   * What an idle segment does until it is evicted. Segments can override it.
+   * Defaults to `keep-running`.
+   */
+  whileIdle?: WhileIdle;
+  /**
+   * How many idle segments may wait for their idle timeout at once. Past it,
+   * the ones idle the longest are evicted right away. Defaults to `Infinity`.
+   */
+  maxIdle?: number;
+  /**
+   * Stops the idle clock while the page is hidden, so that time spent in a
+   * background tab does not count towards the idle timeout. Defaults to `true`.
+   */
+  pauseWhenHidden?: boolean;
+}
+/**
+ * A store enhancer that lets segments be injected into and evicted from a
+ * running store. The root reducer passed to `createStore` keeps owning the
+ * static state; segment slices live next to it under their keys.
+ */
+declare function sparseEnhancer(options?: SparseOptions): StoreEnhancer<SparseStoreExt>;
+//#endregion
+export { StaticState as _, SparseEvent as a, isSegmentKey as b, SparseStoreExt as c, ScopeStateOf as d, Segment as f, StateOfSegments as g, SegmentOptions as h, SparseController as i, sparseEnhancer as l, SegmentEpicStateError as m, SparseAction as n, SparseOptions as o, SegmentEpic as p, SparseActionTypes as r, SparseStats as s, EpicRunner as t, AnySegment as u, WhileIdle as v, defineSegment as y };
+//# sourceMappingURL=sparseEnhancer-CIcdhh-P.d.ts.map

package/package.json

@@ -1,6 +1,114 @@
 {
   "name": "redux-sparse-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dynamic reducers and epics for large Redux stores: only mounted features run on dispatch",
+  "keywords": [
+    "code-splitting",
+    "dynamic-reducers",
+    "lazy-loading",
+    "performance",
+    "react-redux",
+    "redux",
+    "redux-observable"
+  ],
+  "homepage": "https://github.com/veksa/redux-sparse-kit#readme",
+  "bugs": {
+    "url": "https://github.com/veksa/redux-sparse-kit/issues"
+  },
+  "license": "MIT",
+  "author": "Aleksandr Khizhnyi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veksa/redux-sparse-kit.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./observable": {
+      "import": {
+        "types": "./dist/observable.d.mts",
+        "default": "./dist/observable.mjs"
+      },
+      "require": {
+        "types": "./dist/observable.d.ts",
+        "default": "./dist/observable.js"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.mts",
+        "default": "./dist/react.mjs"
+      },
+      "require": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "yarn clean && tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "tsc --noEmit -p _type-tests/tsconfig.json",
+    "lint": "oxlint src/",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "compile": "tsc --noEmit",
+    "clean": "rimraf dist"
+  },
+  "devDependencies": {
+    "@reduxjs/toolkit": "^2.8.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.0.3",
+    "@types/react": "^19.0.12",
+    "@types/react-dom": "^19.0.4",
+    "@veksa/react-redux": "9.3.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "expect-type": "^1.2.1",
+    "jsdom": "^30.0.0",
+    "oxfmt": "^0.61.0",
+    "oxlint": "^1.76.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-redux": "^9.3.0",
+    "redux": "^5.0.1",
+    "redux-observable": "3.0.0-rc.3",
+    "rimraf": "^6.0.1",
+    "rxjs": "^7.8.2",
+    "tsdown": "^0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "redux": "^5.0.0",
+    "rxjs": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "packageManager": "yarn@4.18.0"
+}