@sylphx/lens-signals 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+/** Subscription callback */
+type Subscriber<T> = (value: T) => void;
+/** Unsubscribe function */
+type Unsubscribe = () => void;
+/** Read-only signal interface */
+interface Signal<T> {
+	/** Current value (read-only) */
+	readonly value: T;
+	/** Subscribe to value changes */
+	subscribe(fn: Subscriber<T>): Unsubscribe;
+	/** Get value without tracking */
+	peek(): T;
+}
+/** Writable signal interface */
+interface WritableSignal<T> extends Signal<T> {
+	/** Current value (read-write) */
+	value: T;
+}
+/**
+* Create a writable signal
+*
+* @example
+* ```typescript
+* const count = signal(0);
+* console.log(count.value); // 0
+*
+* count.value = 1;
+* console.log(count.value); // 1
+* ```
+*/
+declare function signal<T>(initial: T): WritableSignal<T>;
+/**
+* Create a computed signal
+*
+* @example
+* ```typescript
+* const count = signal(0);
+* const doubled = computed(() => count.value * 2);
+*
+* console.log(doubled.value); // 0
+*
+* count.value = 5;
+* console.log(doubled.value); // 10
+* ```
+*/
+declare function computed<T>(compute: () => T): Signal<T>;
+/**
+* Run a function whenever dependencies change
+*
+* @example
+* ```typescript
+* const count = signal(0);
+* const dispose = effect(() => {
+*   console.log('Count:', count.value);
+* });
+*
+* count.value = 1; // Logs: "Count: 1"
+* dispose(); // Stop watching
+* ```
+*/
+declare function effect(fn: () => void | (() => void)): Unsubscribe;
+/**
+* Batch multiple signal updates
+*
+* @example
+* ```typescript
+* const a = signal(1);
+* const b = signal(2);
+*
+* batch(() => {
+*   a.value = 10;
+*   b.value = 20;
+* });
+* // Subscribers notified only once
+* ```
+*/
+declare function batch<T>(fn: () => T): T;
+/**
+* Check if a value is a signal
+*/
+declare function isSignal(value: unknown): value is Signal<unknown>;
+/**
+* Convert a signal to a promise that resolves when the signal changes
+*/
+declare function toPromise<T>(sig: Signal<T>): Promise<T>;
+/**
+* Create a signal that derives from multiple signals
+*/
+declare function derive<
+	T,
+	U
+>(signals: Signal<T>[], fn: (values: T[]) => U): Signal<U>;
+import { EntityKey, Pipeline, Update } from "@sylphx/lens-core";
+import { PipelineResult } from "@sylphx/reify";
+/** Entity state with metadata */
+interface EntityState<T = unknown> {
+	/** The entity data */
+	data: T | null;
+	/** Loading state */
+	loading: boolean;
+	/** Error state */
+	error: Error | null;
+	/** Whether data is stale */
+	stale: boolean;
+	/** Subscription reference count */
+	refCount: number;
+	/** Cache timestamp */
+	cachedAt?: number | undefined;
+	/** Cache tags for invalidation */
+	tags?: string[] | undefined;
+}
+/** Optimistic update entry */
+interface OptimisticEntry {
+	id: string;
+	entityName: string;
+	entityId: string;
+	type: "create" | "update" | "delete";
+	originalData: unknown;
+	optimisticData: unknown;
+	timestamp: number;
+}
+/** Multi-entity optimistic transaction */
+interface OptimisticTransaction {
+	id: string;
+	/** Pipeline results from Reify execution */
+	results: PipelineResult;
+	/** Original data for each entity (for rollback) */
+	originalData: Map<string, unknown>;
+	timestamp: number;
+}
+/** Store configuration */
+interface StoreConfig {
+	/** Enable optimistic updates (default: true) */
+	optimistic?: boolean;
+	/** Cache TTL in milliseconds (default: 5 minutes) */
+	cacheTTL?: number;
+	/** Maximum cache size (default: 1000) */
+	maxCacheSize?: number;
+	/** Cascade invalidation rules */
+	cascadeRules?: CascadeRule[];
+}
+/** Cascade invalidation rule */
+interface CascadeRule {
+	/** Source entity type that triggers invalidation */
+	source: string;
+	/** Operation types that trigger cascade (default: all) */
+	operations?: ("create" | "update" | "delete")[];
+	/** Target entities to invalidate */
+	targets: string[];
+}
+/** Invalidation options */
+interface InvalidationOptions {
+	/** Invalidate by tag */
+	tags?: string[];
+	/** Invalidate by entity type pattern (glob-like) */
+	pattern?: string;
+	/** Cascade to related entities */
+	cascade?: boolean;
+}
+/**
+* Reactive store for managing entity state
+*/
+declare class ReactiveStore {
+	/** Entity signals by key */
+	private entities;
+	/** List signals by query key */
+	private lists;
+	/** Optimistic updates pending confirmation */
+	private optimisticUpdates;
+	/** Multi-entity optimistic transactions */
+	private optimisticTransactions;
+	/** Configuration */
+	private config;
+	/** Tag to entity keys mapping */
+	private tagIndex;
+	constructor(config?: StoreConfig);
+	/**
+	* Get or create entity signal
+	*/
+	getEntity<T>(entityName: string, entityId: string): Signal<EntityState<T>>;
+	/**
+	* Set entity data
+	*/
+	setEntity<T>(entityName: string, entityId: string, data: T, tags?: string[]): void;
+	/**
+	* Update entity with server update
+	*/
+	applyServerUpdate(entityName: string, entityId: string, update: Update): void;
+	/**
+	* Set entity error state
+	*/
+	setEntityError(entityName: string, entityId: string, error: Error): void;
+	/**
+	* Set entity loading state
+	*/
+	setEntityLoading(entityName: string, entityId: string, loading: boolean): void;
+	/**
+	* Remove entity from cache
+	*/
+	removeEntity(entityName: string, entityId: string): void;
+	/**
+	* Check if entity exists in cache
+	*/
+	hasEntity(entityName: string, entityId: string): boolean;
+	/**
+	* Get or create list signal
+	*/
+	getList<T>(queryKey: string): Signal<EntityState<T[]>>;
+	/**
+	* Set list data
+	*/
+	setList<T>(queryKey: string, data: T[]): void;
+	/**
+	* Apply optimistic update
+	*/
+	applyOptimistic<T extends {
+		id: string;
+	}>(entityName: string, type: "create" | "update" | "delete", data: Partial<T> & {
+		id: string;
+	}): string;
+	/**
+	* Confirm optimistic update (server confirmed)
+	*/
+	confirmOptimistic(optimisticId: string, serverData?: unknown): void;
+	/**
+	* Rollback optimistic update (server rejected)
+	*/
+	rollbackOptimistic(optimisticId: string): void;
+	/**
+	* Get pending optimistic updates
+	*/
+	getPendingOptimistic(): OptimisticEntry[];
+	/**
+	* Apply optimistic update from Reify Pipeline
+	* Returns transaction ID for confirmation/rollback
+	*
+	* Uses Reify's execute() with a cache adapter that wraps ReactiveStore.
+	*/
+	applyPipelineOptimistic<TInput extends Record<string, unknown>>(pipeline: Pipeline, input: TInput): Promise<string>;
+	/**
+	* Confirm pipeline optimistic transaction
+	* Updates entities with server data (replaces temp IDs with real IDs)
+	*/
+	confirmPipelineOptimistic(txId: string, serverResults?: Array<{
+		entity: string;
+		tempId: string;
+		data: unknown;
+	}>): void;
+	/**
+	* Rollback pipeline optimistic transaction
+	* Restores all entities to their original state
+	*/
+	rollbackPipelineOptimistic(txId: string): void;
+	/**
+	* Get pending multi-entity transactions
+	*/
+	getPendingTransactions(): OptimisticTransaction[];
+	/**
+	* Invalidate entity and mark as stale
+	*/
+	invalidate(entityName: string, entityId: string, options?: InvalidationOptions): void;
+	/**
+	* Invalidate all entities of a type
+	*/
+	invalidateEntity(entityName: string, options?: InvalidationOptions): void;
+	/**
+	* Invalidate by tags
+	*/
+	invalidateByTags(tags: string[]): number;
+	/**
+	* Invalidate by pattern (glob-like: User:*, *:123)
+	*/
+	invalidateByPattern(pattern: string): number;
+	/**
+	* Tag an entity for group invalidation
+	*/
+	tagEntity(entityName: string, entityId: string, tags: string[]): void;
+	/**
+	* Check if entity data is stale (past TTL)
+	*/
+	isStale(entityName: string, entityId: string): boolean;
+	/**
+	* Get data with stale-while-revalidate pattern
+	* Returns stale data immediately and triggers revalidation callback
+	*/
+	getStaleWhileRevalidate<T>(entityName: string, entityId: string, revalidate: () => Promise<T>): {
+		data: T | null;
+		isStale: boolean;
+		revalidating: Promise<T> | null;
+	};
+	private markStale;
+	private cascadeInvalidate;
+	private patternToRegex;
+	/**
+	* Increment reference count for entity
+	*/
+	retain(entityName: string, entityId: string): void;
+	/**
+	* Decrement reference count for entity
+	*/
+	release(entityName: string, entityId: string): void;
+	/**
+	* Clear all stale entities
+	*/
+	gc(): number;
+	/**
+	* Clear entire cache
+	*/
+	clear(): void;
+	/**
+	* Create cache key (delegates to @sylphx/lens-core)
+	*/
+	private makeKey;
+	/**
+	* Get cache statistics
+	*/
+	getStats(): {
+		entities: number;
+		lists: number;
+		pendingOptimistic: number;
+	};
+}
+/**
+* Create a new reactive store
+*/
+declare function createStore(config?: StoreConfig): ReactiveStore;
+export { toPromise, signal, isSignal, effect, derive, createStore, computed, batch, WritableSignal, Unsubscribe, Subscriber, StoreConfig, Signal, ReactiveStore, OptimisticTransaction, OptimisticEntry, InvalidationOptions, EntityState, EntityKey, CascadeRule };