@prabhask5/stellar-engine 1.1.9 → 1.1.10

package/dist/stores/factories.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Store Factory Functions
+ *
+ * Generic factory functions that create Svelte-compatible reactive stores for
+ * common data-loading patterns. These eliminate the repetitive boilerplate that
+ * every collection or detail store requires: loading state management,
+ * sync-complete listener registration, and refresh logic.
+ *
+ * Both factories produce stores that follow the Svelte store contract
+ * (`subscribe`/`unsubscribe`) and expose a read-only `loading` sub-store.
+ *
+ * @see {@link ../engine} for `onSyncComplete` lifecycle hook
+ */
+/**
+ * Configuration for creating a collection store.
+ *
+ * @typeParam T - The entity type stored in the collection.
+ */
+export interface CollectionStoreConfig<T> {
+    /** Async function that fetches the full collection (e.g., from local DB). */
+    load: () => Promise<T[]>;
+}
+/**
+ * A reactive store managing a collection of entities with loading state,
+ * sync-complete auto-refresh, and optimistic mutation support.
+ *
+ * @typeParam T - The entity type stored in the collection.
+ */
+export interface CollectionStore<T> {
+    /** Standard Svelte store subscribe method. */
+    subscribe: (run: (value: T[]) => void) => () => void;
+    /** Read-only loading sub-store. */
+    loading: {
+        subscribe: (run: (value: boolean) => void) => () => void;
+    };
+    /**
+     * Initial load: fetches data, sets loading state, and registers a
+     * sync-complete listener for automatic refresh on future syncs.
+     */
+    load(): Promise<void>;
+    /** Re-fetch data without toggling the loading flag. */
+    refresh(): Promise<void>;
+    /** Replace the store's data directly. */
+    set(data: T[]): void;
+    /** Apply an optimistic mutation to the current data. */
+    mutate(fn: (items: T[]) => T[]): void;
+}
+/**
+ * Configuration for creating a detail store.
+ *
+ * @typeParam T - The entity type for the detail view.
+ */
+export interface DetailStoreConfig<T> {
+    /** Async function that fetches a single entity by ID. */
+    load: (id: string) => Promise<T | null>;
+}
+/**
+ * A reactive store managing a single entity with loading state,
+ * sync-complete auto-refresh, and ID tracking.
+ *
+ * @typeParam T - The entity type for the detail view.
+ */
+export interface DetailStore<T> {
+    /** Standard Svelte store subscribe method. */
+    subscribe: (run: (value: T | null) => void) => () => void;
+    /** Read-only loading sub-store. */
+    loading: {
+        subscribe: (run: (value: boolean) => void) => () => void;
+    };
+    /**
+     * Load a single entity by ID. Registers a sync-complete listener that
+     * auto-refreshes the same entity on future syncs.
+     */
+    load(id: string): Promise<void>;
+    /** Reset the store to null and clear the tracked ID. */
+    clear(): void;
+    /** Replace the store's data directly. */
+    set(data: T | null): void;
+    /** Get the currently tracked entity ID, or null if none loaded. */
+    getCurrentId(): string | null;
+}
+/**
+ * Create a reactive collection store with built-in loading state and
+ * sync-complete auto-refresh.
+ *
+ * The returned store follows the Svelte store contract and can be used with
+ * the `$store` auto-subscription syntax. On the first `load()` call, a
+ * sync-complete listener is registered so the collection automatically
+ * refreshes whenever the sync engine completes a cycle.
+ *
+ * Uses `typeof window !== 'undefined'` for environment detection since
+ * stellar-engine is a library (not tied to SvelteKit's `browser` export).
+ *
+ * @typeParam T - The entity type stored in the collection.
+ * @param config - Configuration with a `load` function.
+ * @returns A `CollectionStore<T>` instance.
+ *
+ * @example
+ * ```ts
+ * import { createCollectionStore } from '@prabhask5/stellar-engine/stores';
+ *
+ * const store = createCollectionStore<Task>({
+ *   load: () => queryAll<Task>('tasks'),
+ * });
+ *
+ * // In your component:
+ * await store.load();
+ * // $store is now Task[], $store.loading is boolean
+ * ```
+ */
+export declare function createCollectionStore<T>(config: CollectionStoreConfig<T>): CollectionStore<T>;
+/**
+ * Create a reactive detail store for a single entity, with built-in loading
+ * state, ID tracking, and sync-complete auto-refresh.
+ *
+ * The store tracks the currently loaded entity ID so that sync-complete
+ * listeners can refresh the correct entity. Calling `load(id)` with a
+ * different ID updates the tracked ID and fetches the new entity.
+ *
+ * @typeParam T - The entity type for the detail view.
+ * @param config - Configuration with a `load` function that takes an entity ID.
+ * @returns A `DetailStore<T>` instance.
+ *
+ * @example
+ * ```ts
+ * import { createDetailStore } from '@prabhask5/stellar-engine/stores';
+ *
+ * const store = createDetailStore<Task>({
+ *   load: (id) => queryOne<Task>('tasks', id),
+ * });
+ *
+ * // In your component:
+ * await store.load(taskId);
+ * // $store is now Task | null, $store.loading is boolean
+ * ```
+ */
+export declare function createDetailStore<T>(config: DetailStoreConfig<T>): DetailStore<T>;
+//# sourceMappingURL=factories.d.ts.map

package/dist/stores/factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/stores/factories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,6EAA6E;IAC7E,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,8CAA8C;IAC9C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAErD,mCAAmC;IACnC,OAAO,EAAE;QAAE,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;KAAE,CAAC;IAEtE;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,uDAAuD;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,yCAAyC;IACzC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IAErB,wDAAwD;IACxD,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,yDAAyD;IACzD,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,8CAA8C;IAC9C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAE1D,mCAAmC;IACnC,OAAO,EAAE;QAAE,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;KAAE,CAAC;IAEtE;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;IAEd,yCAAyC;IACzC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAE1B,mEAAmE;IACnE,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAyC7F;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CA6CjF"}

package/dist/stores/factories.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Store Factory Functions
+ *
+ * Generic factory functions that create Svelte-compatible reactive stores for
+ * common data-loading patterns. These eliminate the repetitive boilerplate that
+ * every collection or detail store requires: loading state management,
+ * sync-complete listener registration, and refresh logic.
+ *
+ * Both factories produce stores that follow the Svelte store contract
+ * (`subscribe`/`unsubscribe`) and expose a read-only `loading` sub-store.
+ *
+ * @see {@link ../engine} for `onSyncComplete` lifecycle hook
+ */
+import { writable } from 'svelte/store';
+import { onSyncComplete } from '../engine';
+// =============================================================================
+// Collection Store Factory
+// =============================================================================
+/**
+ * Create a reactive collection store with built-in loading state and
+ * sync-complete auto-refresh.
+ *
+ * The returned store follows the Svelte store contract and can be used with
+ * the `$store` auto-subscription syntax. On the first `load()` call, a
+ * sync-complete listener is registered so the collection automatically
+ * refreshes whenever the sync engine completes a cycle.
+ *
+ * Uses `typeof window !== 'undefined'` for environment detection since
+ * stellar-engine is a library (not tied to SvelteKit's `browser` export).
+ *
+ * @typeParam T - The entity type stored in the collection.
+ * @param config - Configuration with a `load` function.
+ * @returns A `CollectionStore<T>` instance.
+ *
+ * @example
+ * ```ts
+ * import { createCollectionStore } from '@prabhask5/stellar-engine/stores';
+ *
+ * const store = createCollectionStore<Task>({
+ *   load: () => queryAll<Task>('tasks'),
+ * });
+ *
+ * // In your component:
+ * await store.load();
+ * // $store is now Task[], $store.loading is boolean
+ * ```
+ */
+export function createCollectionStore(config) {
+    const { subscribe, set, update } = writable([]);
+    const loading = writable(true);
+    let syncUnsubscribe = null;
+    return {
+        subscribe,
+        loading: { subscribe: loading.subscribe },
+        async load() {
+            loading.set(true);
+            try {
+                const data = await config.load();
+                set(data);
+                /* Register sync-complete listener once, only in the browser.
+                   On each sync cycle, the collection auto-refreshes from local DB. */
+                if (typeof window !== 'undefined' && !syncUnsubscribe) {
+                    syncUnsubscribe = onSyncComplete(async () => {
+                        const refreshed = await config.load();
+                        set(refreshed);
+                    });
+                }
+            }
+            finally {
+                loading.set(false);
+            }
+        },
+        async refresh() {
+            const data = await config.load();
+            set(data);
+        },
+        set(data) {
+            set(data);
+        },
+        mutate(fn) {
+            update(fn);
+        }
+    };
+}
+// =============================================================================
+// Detail Store Factory
+// =============================================================================
+/**
+ * Create a reactive detail store for a single entity, with built-in loading
+ * state, ID tracking, and sync-complete auto-refresh.
+ *
+ * The store tracks the currently loaded entity ID so that sync-complete
+ * listeners can refresh the correct entity. Calling `load(id)` with a
+ * different ID updates the tracked ID and fetches the new entity.
+ *
+ * @typeParam T - The entity type for the detail view.
+ * @param config - Configuration with a `load` function that takes an entity ID.
+ * @returns A `DetailStore<T>` instance.
+ *
+ * @example
+ * ```ts
+ * import { createDetailStore } from '@prabhask5/stellar-engine/stores';
+ *
+ * const store = createDetailStore<Task>({
+ *   load: (id) => queryOne<Task>('tasks', id),
+ * });
+ *
+ * // In your component:
+ * await store.load(taskId);
+ * // $store is now Task | null, $store.loading is boolean
+ * ```
+ */
+export function createDetailStore(config) {
+    const { subscribe, set } = writable(null);
+    const loading = writable(true);
+    let currentId = null;
+    let syncUnsubscribe = null;
+    return {
+        subscribe,
+        loading: { subscribe: loading.subscribe },
+        async load(id) {
+            currentId = id;
+            loading.set(true);
+            try {
+                const data = await config.load(id);
+                set(data);
+                /* Register sync-complete listener once, only in the browser.
+                   Uses the tracked `currentId` so it always refreshes the active entity. */
+                if (typeof window !== 'undefined' && !syncUnsubscribe) {
+                    syncUnsubscribe = onSyncComplete(async () => {
+                        if (currentId) {
+                            const refreshed = await config.load(currentId);
+                            set(refreshed);
+                        }
+                    });
+                }
+            }
+            finally {
+                loading.set(false);
+            }
+        },
+        clear() {
+            currentId = null;
+            set(null);
+        },
+        set(data) {
+            set(data);
+        },
+        getCurrentId() {
+            return currentId;
+        }
+    };
+}
+//# sourceMappingURL=factories.js.map

package/dist/stores/factories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.js","sourceRoot":"","sources":["../../src/stores/factories.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prabhask5/stellar-engine",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",