@directive-run/core 0.4.0 → 0.4.1

package/dist/plugins/index.d.cts

@@ -4,18 +4,44 @@ import { M as ModuleSchema, P as Plugin, J as System } from '../plugins-cDWoL7A7
  * Logging Plugin - Console logging for Directive events
  */
 
+/**
+ * Configuration for the {@link loggingPlugin}.
+ *
+ * @remarks
+ * All fields are optional. The defaults produce `[Directive]`-prefixed
+ * `console.info`-level output for every lifecycle event.
+ *
+ * | Field    | Default         | Description |
+ * |----------|-----------------|-------------|
+ * | `level`  | `"info"`        | Minimum severity to emit. |
+ * | `filter` | `() => true`    | Predicate that receives the event name (e.g., `"fact.set"`) and returns whether to log it. |
+ * | `logger` | `console`       | Any object implementing `debug`, `info`, `warn`, `error`, `group`, and `groupEnd`. |
+ * | `prefix` | `"[Directive]"` | String prepended to every log line. |
+ *
+ * @public
+ */
 interface LoggingPluginOptions {
-    /** Log level */
+    /** Minimum log level; events below this severity are silenced. */
     level?: "debug" | "info" | "warn" | "error";
-    /** Filter function to include/exclude events */
+    /** Predicate that receives the event name and returns whether to log it. */
     filter?: (event: string) => boolean;
-    /** Custom logger (defaults to console) */
+    /** Custom logger object (defaults to `console`). */
     logger?: Pick<Console, "debug" | "info" | "warn" | "error" | "group" | "groupEnd">;
-    /** Prefix for log messages */
+    /** String prepended to every log message. */
     prefix?: string;
 }
 /**
- * Create a logging plugin.
+ * Create a plugin that logs Directive lifecycle events to a configurable logger.
+ *
+ * @remarks
+ * Every plugin hook is mapped to a log call at an appropriate severity:
+ * - `debug` -- init, destroy, fact changes, derivation compute/invalidate, reconcile, constraint evaluate, resolver start/cancel, effect run, snapshot
+ * - `info` -- start, stop, requirement met, resolver complete, time-travel jump
+ * - `warn` -- resolver retry, error recovery
+ * - `error` -- constraint error, resolver error, effect error, system error
+ *
+ * @param options - Optional {@link LoggingPluginOptions} to control level, filtering, logger backend, and prefix.
+ * @returns A {@link Plugin} that can be passed to `createSystem`'s `plugins` array.
  *
  * @example
  * ```ts
@@ -24,6 +50,8 @@ interface LoggingPluginOptions {
  *   plugins: [loggingPlugin({ level: "debug" })],
  * });
  * ```
+ *
+ * @public
  */
 declare function loggingPlugin<M extends ModuleSchema = ModuleSchema>(options?: LoggingPluginOptions): Plugin<M>;
 
@@ -164,26 +192,60 @@ declare function emitDevToolsEvent(event: Record<string, unknown> & {
  * Persistence Plugin - Save/restore facts to storage
  */
 
+/**
+ * Configuration for the {@link persistencePlugin}.
+ *
+ * @remarks
+ * At minimum, provide a `storage` backend and a `key`. Use `include` or
+ * `exclude` to control which fact keys are persisted. Saves are debounced
+ * by default (100 ms) to avoid excessive writes during rapid updates.
+ *
+ * | Field       | Default | Description |
+ * |-------------|---------|-------------|
+ * | `storage`   | *(required)* | A `Storage`-compatible backend (`localStorage`, `sessionStorage`, or custom). |
+ * | `key`       | *(required)* | The key used to read/write from storage. |
+ * | `include`   | all keys | Whitelist of fact keys to persist. |
+ * | `exclude`   | `[]`    | Blacklist of fact keys to skip. |
+ * | `debounce`  | `100`   | Milliseconds to debounce saves. |
+ * | `onRestore` | --      | Callback fired after state is restored from storage. |
+ * | `onSave`    | --      | Callback fired after state is written to storage. |
+ * | `onError`   | --      | Callback fired when a load or save error occurs. |
+ *
+ * @public
+ */
 interface PersistencePluginOptions {
-    /** Storage backend (localStorage, sessionStorage, or custom) */
+    /** A `Storage`-compatible backend (`localStorage`, `sessionStorage`, or custom). */
     storage: Storage;
-    /** Key to use in storage */
+    /** The key used to read/write from the storage backend. */
     key: string;
-    /** Only persist these fact keys (default: all) */
+    /** Whitelist of fact keys to persist (default: all keys). */
     include?: string[];
-    /** Exclude these fact keys from persistence */
+    /** Fact keys to exclude from persistence. */
     exclude?: string[];
-    /** Debounce saves by this many ms (default: 100) */
+    /** Milliseconds to debounce saves (default: 100). */
     debounce?: number;
-    /** Called when state is restored */
+    /** Callback fired after state is restored from storage on init. */
     onRestore?: (data: Record<string, unknown>) => void;
-    /** Called when state is saved */
+    /** Callback fired after state is written to storage. */
     onSave?: (data: Record<string, unknown>) => void;
-    /** Called on error */
+    /** Callback fired when a load or save error occurs. */
     onError?: (error: Error) => void;
 }
 /**
- * Create a persistence plugin.
+ * Create a plugin that persists selected facts to a `Storage` backend and
+ * restores them on system init.
+ *
+ * @remarks
+ * On `onInit`, the plugin reads the storage key and batch-sets any persisted
+ * facts into the store. On every `onFactSet` / `onFactDelete` / `onFactsBatch`,
+ * a debounced save is scheduled. A final synchronous save runs on `onDestroy`
+ * to capture any pending changes.
+ *
+ * Stored data is validated against prototype pollution before restoration
+ * via {@link isPrototypeSafe}.
+ *
+ * @param options - Required {@link PersistencePluginOptions} specifying storage backend, key, and optional filters/callbacks.
+ * @returns A {@link Plugin} that can be passed to `createSystem`'s `plugins` array.
  *
  * @example
  * ```ts
@@ -198,6 +260,8 @@ interface PersistencePluginOptions {
  *   ],
  * });
  * ```
+ *
+ * @public
  */
 declare function persistencePlugin<M extends ModuleSchema = ModuleSchema>(options: PersistencePluginOptions): Plugin<M>;
 
@@ -747,6 +811,9 @@ declare class CircuitBreakerOpenError extends Error {
 /**
  * Create a circuit breaker for protecting against cascading failures.
  *
+ * @param config - Circuit breaker configuration (thresholds, recovery time, observability)
+ * @returns A circuit breaker instance with `execute`, `getState`, and `reset` methods
+ *
  * @example
  * ```typescript
  * const breaker = createCircuitBreaker({
@@ -767,10 +834,10 @@ declare class CircuitBreakerOpenError extends Error {
  * }
  * ```
  *
- * @throws {Error} If failureThreshold is less than 1 or not a finite number
- * @throws {Error} If recoveryTimeMs is not positive or not a finite number
- * @throws {Error} If halfOpenMaxRequests is less than 1 or not a finite number
- * @throws {Error} If failureWindowMs is not positive or not a finite number
+ * @throws If failureThreshold is less than 1 or not a finite number
+ * @throws If recoveryTimeMs is not positive or not a finite number
+ * @throws If halfOpenMaxRequests is less than 1 or not a finite number
+ * @throws If failureWindowMs is not positive or not a finite number
  */
 declare function createCircuitBreaker(config?: CircuitBreakerConfig): CircuitBreaker;
 

package/dist/plugins/index.d.ts

@@ -4,18 +4,44 @@ import { M as ModuleSchema, P as Plugin, J as System } from '../plugins-cDWoL7A7
  * Logging Plugin - Console logging for Directive events
  */
 
+/**
+ * Configuration for the {@link loggingPlugin}.
+ *
+ * @remarks
+ * All fields are optional. The defaults produce `[Directive]`-prefixed
+ * `console.info`-level output for every lifecycle event.
+ *
+ * | Field    | Default         | Description |
+ * |----------|-----------------|-------------|
+ * | `level`  | `"info"`        | Minimum severity to emit. |
+ * | `filter` | `() => true`    | Predicate that receives the event name (e.g., `"fact.set"`) and returns whether to log it. |
+ * | `logger` | `console`       | Any object implementing `debug`, `info`, `warn`, `error`, `group`, and `groupEnd`. |
+ * | `prefix` | `"[Directive]"` | String prepended to every log line. |
+ *
+ * @public
+ */
 interface LoggingPluginOptions {
-    /** Log level */
+    /** Minimum log level; events below this severity are silenced. */
     level?: "debug" | "info" | "warn" | "error";
-    /** Filter function to include/exclude events */
+    /** Predicate that receives the event name and returns whether to log it. */
     filter?: (event: string) => boolean;
-    /** Custom logger (defaults to console) */
+    /** Custom logger object (defaults to `console`). */
     logger?: Pick<Console, "debug" | "info" | "warn" | "error" | "group" | "groupEnd">;
-    /** Prefix for log messages */
+    /** String prepended to every log message. */
     prefix?: string;
 }
 /**
- * Create a logging plugin.
+ * Create a plugin that logs Directive lifecycle events to a configurable logger.
+ *
+ * @remarks
+ * Every plugin hook is mapped to a log call at an appropriate severity:
+ * - `debug` -- init, destroy, fact changes, derivation compute/invalidate, reconcile, constraint evaluate, resolver start/cancel, effect run, snapshot
+ * - `info` -- start, stop, requirement met, resolver complete, time-travel jump
+ * - `warn` -- resolver retry, error recovery
+ * - `error` -- constraint error, resolver error, effect error, system error
+ *
+ * @param options - Optional {@link LoggingPluginOptions} to control level, filtering, logger backend, and prefix.
+ * @returns A {@link Plugin} that can be passed to `createSystem`'s `plugins` array.
  *
  * @example
  * ```ts
@@ -24,6 +50,8 @@ interface LoggingPluginOptions {
  *   plugins: [loggingPlugin({ level: "debug" })],
  * });
  * ```
+ *
+ * @public
  */
 declare function loggingPlugin<M extends ModuleSchema = ModuleSchema>(options?: LoggingPluginOptions): Plugin<M>;
 
@@ -164,26 +192,60 @@ declare function emitDevToolsEvent(event: Record<string, unknown> & {
  * Persistence Plugin - Save/restore facts to storage
  */
 
+/**
+ * Configuration for the {@link persistencePlugin}.
+ *
+ * @remarks
+ * At minimum, provide a `storage` backend and a `key`. Use `include` or
+ * `exclude` to control which fact keys are persisted. Saves are debounced
+ * by default (100 ms) to avoid excessive writes during rapid updates.
+ *
+ * | Field       | Default | Description |
+ * |-------------|---------|-------------|
+ * | `storage`   | *(required)* | A `Storage`-compatible backend (`localStorage`, `sessionStorage`, or custom). |
+ * | `key`       | *(required)* | The key used to read/write from storage. |
+ * | `include`   | all keys | Whitelist of fact keys to persist. |
+ * | `exclude`   | `[]`    | Blacklist of fact keys to skip. |
+ * | `debounce`  | `100`   | Milliseconds to debounce saves. |
+ * | `onRestore` | --      | Callback fired after state is restored from storage. |
+ * | `onSave`    | --      | Callback fired after state is written to storage. |
+ * | `onError`   | --      | Callback fired when a load or save error occurs. |
+ *
+ * @public
+ */
 interface PersistencePluginOptions {
-    /** Storage backend (localStorage, sessionStorage, or custom) */
+    /** A `Storage`-compatible backend (`localStorage`, `sessionStorage`, or custom). */
     storage: Storage;
-    /** Key to use in storage */
+    /** The key used to read/write from the storage backend. */
     key: string;
-    /** Only persist these fact keys (default: all) */
+    /** Whitelist of fact keys to persist (default: all keys). */
     include?: string[];
-    /** Exclude these fact keys from persistence */
+    /** Fact keys to exclude from persistence. */
     exclude?: string[];
-    /** Debounce saves by this many ms (default: 100) */
+    /** Milliseconds to debounce saves (default: 100). */
     debounce?: number;
-    /** Called when state is restored */
+    /** Callback fired after state is restored from storage on init. */
     onRestore?: (data: Record<string, unknown>) => void;
-    /** Called when state is saved */
+    /** Callback fired after state is written to storage. */
     onSave?: (data: Record<string, unknown>) => void;
-    /** Called on error */
+    /** Callback fired when a load or save error occurs. */
     onError?: (error: Error) => void;
 }
 /**
- * Create a persistence plugin.
+ * Create a plugin that persists selected facts to a `Storage` backend and
+ * restores them on system init.
+ *
+ * @remarks
+ * On `onInit`, the plugin reads the storage key and batch-sets any persisted
+ * facts into the store. On every `onFactSet` / `onFactDelete` / `onFactsBatch`,
+ * a debounced save is scheduled. A final synchronous save runs on `onDestroy`
+ * to capture any pending changes.
+ *
+ * Stored data is validated against prototype pollution before restoration
+ * via {@link isPrototypeSafe}.
+ *
+ * @param options - Required {@link PersistencePluginOptions} specifying storage backend, key, and optional filters/callbacks.
+ * @returns A {@link Plugin} that can be passed to `createSystem`'s `plugins` array.
  *
  * @example
  * ```ts
@@ -198,6 +260,8 @@ interface PersistencePluginOptions {
  *   ],
  * });
  * ```
+ *
+ * @public
  */
 declare function persistencePlugin<M extends ModuleSchema = ModuleSchema>(options: PersistencePluginOptions): Plugin<M>;
 
@@ -747,6 +811,9 @@ declare class CircuitBreakerOpenError extends Error {
 /**
  * Create a circuit breaker for protecting against cascading failures.
  *
+ * @param config - Circuit breaker configuration (thresholds, recovery time, observability)
+ * @returns A circuit breaker instance with `execute`, `getState`, and `reset` methods
+ *
  * @example
  * ```typescript
  * const breaker = createCircuitBreaker({
@@ -767,10 +834,10 @@ declare class CircuitBreakerOpenError extends Error {
  * }
  * ```
  *
- * @throws {Error} If failureThreshold is less than 1 or not a finite number
- * @throws {Error} If recoveryTimeMs is not positive or not a finite number
- * @throws {Error} If halfOpenMaxRequests is less than 1 or not a finite number
- * @throws {Error} If failureWindowMs is not positive or not a finite number
+ * @throws If failureThreshold is less than 1 or not a finite number
+ * @throws If recoveryTimeMs is not positive or not a finite number
+ * @throws If halfOpenMaxRequests is less than 1 or not a finite number
+ * @throws If failureWindowMs is not positive or not a finite number
  */
 declare function createCircuitBreaker(config?: CircuitBreakerConfig): CircuitBreaker;