@stone-js/store 0.8.14 → 0.8.16

package/dist/decorators/FeatureStore.d.ts

@@ -0,0 +1,49 @@
+import { ClassType } from '@stone-js/core';
+/** Options for the `@FeatureStore` declaration. */
+export interface FeatureStoreOptions {
+    /**
+     * Whether the server keeps one instance per request. Default `true`, deliberately: a shared store
+     * leaks one visitor's state into the next visitor's page during server rendering, and the leak is
+     * invisible in development where there is only ever one request at a time.
+     */
+    perRequest?: boolean;
+}
+/**
+ * Declare a class as a feature's store.
+ *
+ * A feature owns its client, its service and its state, and this is how the state half is declared:
+ * a class extending `StateStore`, holding the actions that move it. Two statements in one, the way
+ * every declaration decorator works here:
+ *
+ * 1. **The container builds it.** Its constructor is auto-wired like any other class, which is what a
+ *    data definition cannot express: the store's actions call the services they were handed.
+ * 2. **It activates the module.** The blueprint comes with the decorator, so declaring a store is the
+ *    whole setup, and it is resolved under `store.<name>`, hydrated from the snapshot, and given the
+ *    per-request lifetime, exactly like a store declared as data.
+ *
+ * The imperative counterpart is `defineStore(CompetitionStore, { name: 'competition' })`, and the two
+ * declare the same thing: neither paradigm can do something the other cannot.
+ *
+ * @param name - The name it is resolved under, in the container and in the snapshot. Defaults to the
+ *               class name.
+ * @param options - The lifetime.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @FeatureStore('competition')
+ * export class CompetitionStore extends StateStore<CompetitionState> {
+ *   private readonly client: CompetitionClient
+ *
+ *   constructor ({ competitionClient }: { competitionClient: CompetitionClient }) {
+ *     super({ list: [], selected: undefined })
+ *     this.client = competitionClient
+ *   }
+ *
+ *   async load (): Promise<void> {
+ *     this.setState({ list: await this.client.list() })
+ *   }
+ * }
+ * ```
+ */
+export declare const FeatureStore: <T extends ClassType = ClassType>(name?: string, options?: FeatureStoreOptions) => ClassDecorator;

package/dist/decorators/Store.d.ts

@@ -1,11 +1,11 @@
-import { StoreDefinition } from '../defineStore.js';
+import { StoreRegistration } from '../defineStore.js';
 import { ClassType } from '@stone-js/core';
 /**
  * Options for the `@Store` decorator: the stores to declare, and the `stone.store` bucket.
  */
 export interface StoreDecoratorOptions {
     /** The stores this application declares. */
-    stores?: StoreDefinition[];
+    stores?: StoreRegistration[];
     /** The snapshot key the hydrated states live under. */
     snapshotKey?: string;
 }

package/dist/defineStore.d.ts

@@ -18,25 +18,92 @@ export interface StoreDefinition<State extends Record<string, any> = Record<stri
      */
     perRequest?: boolean;
 }
+/**
+ * A store written as a class: a feature's state and the actions that move it, together.
+ *
+ * The container builds it, so its constructor is auto-wired like any other class. That is what a data
+ * definition cannot express and the reason the class form exists: a `competition` module has its
+ * client, its service and its store, and the store's actions call the client.
+ */
+export type StoreClass<State extends Record<string, any> = Record<string, any>> = new (...args: any[]) => IStore<State>;
+/** A store built by a factory. It receives the container, and returns the store. */
+export type StoreFactory<State extends Record<string, any> = Record<string, any>> = (container: any) => IStore<State>;
+/**
+ * A registered store, in any of the three forms the framework accepts everywhere else.
+ *
+ * The data definition plays the plain role: state with no behaviour. The class and the factory carry
+ * behaviour, and both are built through the container, so a store can hold the services its actions
+ * need. `stone.store.stores` accepts any mix of the three.
+ */
+export interface MetaStore<State extends Record<string, any> = Record<string, any>> {
+    /** The name it is resolved under, in the container and in the snapshot. */
+    name: string;
+    /** The class or the factory to build. */
+    module: StoreClass<State> | StoreFactory<State>;
+    /** Whether `module` is a class to construct. */
+    isClass?: boolean;
+    /** Whether `module` is a factory to call with the container. */
+    isFactory?: boolean;
+    /** Same semantics as {@link StoreDefinition.perRequest}, same default. */
+    perRequest?: boolean;
+}
+/** Anything `stone.store.stores` accepts. */
+export type StoreRegistration<State extends Record<string, any> = Record<string, any>> = StoreDefinition<State> | MetaStore<State>;
+/** Options for the class and factory forms of {@link defineStore}. */
+export interface DefineStoreOptions {
+    /** The name it is resolved under. Defaults to the class name for a class; required for a factory. */
+    name?: string;
+    /** Whether the module is a factory rather than a class. */
+    isFactory?: boolean;
+    /** Same semantics as {@link StoreDefinition.perRequest}, same default. */
+    perRequest?: boolean;
+}
 /**
  * Declare a store, imperatively.
  *
- * The counterpart of the `@Store()` decorator: same declaration, same registration, no decorators
- * required. Both end up in `stone.store.stores`, which is what the provider registers.
+ * Three forms, mirroring the rest of the framework. A data definition for state with no behaviour, a
+ * class for a feature whose store carries actions, and a factory for full control over construction.
+ * The class and factory forms are the imperative counterpart of `@FeatureStore()`: same declaration,
+ * same registration, no decorators required. Everything ends up in `stone.store.stores`, which is
+ * what the provider registers.
  *
- * @param definition - What the store declares.
- * @returns The definition, ready to be handed to the blueprint.
+ * @param definition - A data definition, a store class, or a store factory.
+ * @param options - The name and lifetime, for the class and factory forms.
+ * @returns The registration, ready to be handed to the blueprint.
  *
  * @example
  * ```typescript
+ * // Data: state with no behaviour.
  * export const tasksStore = defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })
+ *
+ * // Class: the container builds it, so its actions can use injected services.
+ * export const competitionStore = defineStore(CompetitionStore, { name: 'competition' })
+ *
+ * // Factory: full control, the container in hand.
+ * export const liveStore = defineStore(
+ *   (container) => StateStore.create({ scores: container.make('feed').initial() }),
+ *   { name: 'live', isFactory: true }
+ * )
  * ```
  */
 export declare function defineStore<State extends Record<string, any>>(definition: StoreDefinition<State>): StoreDefinition<State>;
+export declare function defineStore<State extends Record<string, any>>(definition: StoreClass<State> | StoreFactory<State>, options: DefineStoreOptions): MetaStore<State>;
 /**
- * Build a store from its definition.
+ * Whether a registration carries a module to build, rather than plain state.
+ *
+ * @param registration - The registration.
+ * @returns True for the class and factory forms.
+ */
+export declare function isMetaStore<State extends Record<string, any>>(registration: StoreRegistration<State>): registration is MetaStore<State>;
+/**
+ * Build a store from its registration, whichever form it was declared in.
+ *
+ * A class is constructed with the container, which is what auto-wires the services its actions use; a
+ * factory is called with it; a data definition needs nothing. The container is only required by the
+ * forms that use it, so building a plain store stays dependency-free.
  *
- * @param definition - What the store declares.
+ * @param registration - The registration.
+ * @param container - The container, for the class and factory forms.
  * @returns A new store.
  */
-export declare function makeStore<State extends Record<string, any>>(definition: StoreDefinition<State>): IStore<State>;
+export declare function makeStore<State extends Record<string, any>>(registration: StoreRegistration<State>, container?: any): IStore<State>;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './declarations.js';
+export * from './decorators/FeatureStore.js';
 export * from './decorators/Store.js';
 export * from './defineStore.js';
 export * from './options/StoreBlueprint.js';

package/dist/index.js

@@ -158,31 +158,49 @@ class StateStore {
     }
 }
 
+function defineStore(definition, options = {}) {
+    if (typeof definition !== 'function') {
+        return definition;
+    }
+    const name = options.name ?? definition.name;
+    if (name === undefined || name === '') {
+        throw new TypeError('A class or factory store needs a name: pass `{ name }`, since an anonymous function has none to fall back on.');
+    }
+    return {
+        name,
+        module: definition,
+        isClass: options.isFactory !== true,
+        isFactory: options.isFactory === true,
+        perRequest: options.perRequest
+    };
+}
 /**
- * Declare a store, imperatively.
- *
- * The counterpart of the `@Store()` decorator: same declaration, same registration, no decorators
- * required. Both end up in `stone.store.stores`, which is what the provider registers.
+ * Whether a registration carries a module to build, rather than plain state.
  *
- * @param definition - What the store declares.
- * @returns The definition, ready to be handed to the blueprint.
- *
- * @example
- * ```typescript
- * export const tasksStore = defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })
- * ```
+ * @param registration - The registration.
+ * @returns True for the class and factory forms.
  */
-function defineStore(definition) {
-    return definition;
+function isMetaStore(registration) {
+    return typeof registration.module === 'function';
 }
 /**
- * Build a store from its definition.
+ * Build a store from its registration, whichever form it was declared in.
  *
- * @param definition - What the store declares.
+ * A class is constructed with the container, which is what auto-wires the services its actions use; a
+ * factory is called with it; a data definition needs nothing. The container is only required by the
+ * forms that use it, so building a plain store stays dependency-free.
+ *
+ * @param registration - The registration.
+ * @param container - The container, for the class and factory forms.
  * @returns A new store.
  */
-function makeStore(definition) {
-    return StateStore.create(definition.state);
+function makeStore(registration, container) {
+    if (!isMetaStore(registration)) {
+        return StateStore.create(registration.state);
+    }
+    return registration.isFactory === true
+        ? registration.module(container)
+        : new registration.module(container);
 }
 
 /**
@@ -228,7 +246,9 @@ class StoreServiceProvider {
         const hydrated = this.hydratedStates(options.snapshotKey ?? 'stores');
         for (const definition of options.stores ?? []) {
             const build = () => {
-                const store = makeStore(definition);
+                // The container is what auto-wires a class store's constructor and what a factory receives;
+                // a plain data definition ignores it.
+                const store = makeStore(definition, this.container);
                 const state = hydrated[definition.name];
                 // Adopted before anything can read the store, so the first render already has real state.
                 if (state !== undefined) {
@@ -295,6 +315,61 @@ const storeBlueprint = {
     }
 };
 
+/**
+ * Declare a class as a feature's store.
+ *
+ * A feature owns its client, its service and its state, and this is how the state half is declared:
+ * a class extending `StateStore`, holding the actions that move it. Two statements in one, the way
+ * every declaration decorator works here:
+ *
+ * 1. **The container builds it.** Its constructor is auto-wired like any other class, which is what a
+ *    data definition cannot express: the store's actions call the services they were handed.
+ * 2. **It activates the module.** The blueprint comes with the decorator, so declaring a store is the
+ *    whole setup, and it is resolved under `store.<name>`, hydrated from the snapshot, and given the
+ *    per-request lifetime, exactly like a store declared as data.
+ *
+ * The imperative counterpart is `defineStore(CompetitionStore, { name: 'competition' })`, and the two
+ * declare the same thing: neither paradigm can do something the other cannot.
+ *
+ * @param name - The name it is resolved under, in the container and in the snapshot. Defaults to the
+ *               class name.
+ * @param options - The lifetime.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @FeatureStore('competition')
+ * export class CompetitionStore extends StateStore<CompetitionState> {
+ *   private readonly client: CompetitionClient
+ *
+ *   constructor ({ competitionClient }: { competitionClient: CompetitionClient }) {
+ *     super({ list: [], selected: undefined })
+ *     this.client = competitionClient
+ *   }
+ *
+ *   async load (): Promise<void> {
+ *     this.setState({ list: await this.client.list() })
+ *   }
+ * }
+ * ```
+ */
+const FeatureStore = (name, options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        addBlueprint(target, context, storeBlueprint, {
+            stone: {
+                store: {
+                    stores: [{
+                            name: name ?? target.name,
+                            module: target,
+                            isClass: true,
+                            perRequest: options.perRequest
+                        }]
+                }
+            }
+        });
+    });
+};
+
 /**
  * Class decorator: give the application a store, declaratively.
  *
@@ -324,4 +399,4 @@ const Store = (options = {}) => {
     });
 };
 
-export { StateStore, Store, StoreServiceProvider, defineStore, makeStore, sameValue, storeAlias, storeBlueprint };
+export { FeatureStore, StateStore, Store, StoreServiceProvider, defineStore, isMetaStore, makeStore, sameValue, storeAlias, storeBlueprint };

package/dist/options/StoreBlueprint.d.ts

@@ -1,4 +1,4 @@
-import { StoreDefinition } from '../defineStore.js';
+import { StoreRegistration } from '../defineStore.js';
 import { AppConfig, StoneBlueprint } from '@stone-js/core';
 /**
  * Store configuration bucket (`stone.store`).
@@ -9,7 +9,7 @@ export interface StoreConfig {
      *
      * Filled by `@Store()` and by handing `defineStore(...)` definitions here.
      */
-    stores?: StoreDefinition[];
+    stores?: StoreRegistration[];
     /**
      * The snapshot key the hydrated states live under. Default `'stores'`.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/store",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "description": "View-engine-agnostic universal store for Stone.js, with SSR hydration built in.",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
@@ -54,7 +54,8 @@
     "typedoc": "^0.28.6",
     "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@stone-js/service-container": "0.8.16"
   },
   "ts-standard": {
     "globals": [
@@ -67,10 +68,10 @@
     ]
   },
   "dependencies": {
-    "@stone-js/config": "0.8.14"
+    "@stone-js/config": "0.8.16"
   },
   "peerDependencies": {
-    "@stone-js/core": "0.8.14"
+    "@stone-js/core": "0.8.16"
   },
   "scripts": {
     "lint": "ts-standard src",