@dvina/sdk 3.3.124

package/dist/adapters/angular/index.d.ts

@@ -0,0 +1,254 @@
+import { Signal, DestroyRef, EnvironmentProviders } from '@angular/core';
+import { D as DvinaSdkOptions } from '../../client-Bskq7sc_.js';
+import { D as DvinaQueryRef } from '../../types-2RotD0Ab.js';
+import '../../error-CsVoUTY8.js';
+import '../../sync-engine-cLwTqdjv.js';
+import 'graphql';
+import 'dexie';
+import '../../client-CLhQragb.js';
+import '../../billing/index.js';
+
+/**
+ * Angular adapter for @dvina/sdk.
+ *
+ * Provides primitives for integrating the Dvina SDK with Angular's DI and signal system:
+ *
+ * - {@link provideDvina} — register a singleton `DvinaSdk` instance in the Angular DI system
+ * - {@link toSignal} — lightweight converter from `DvinaQueryRef` to a readonly `Signal`
+ * - {@link dvnResource} — full resource primitive inspired by Angular's `resource()` API,
+ *   supporting both `Promise` and `AsyncIterable` loaders with reactive params tracking,
+ *   status/error signals, and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * import { provideDvina, toSignal, dvnResource } from '@dvina/sdk/angular';
+ * import { DvinaSdk } from '@dvina/sdk';
+ *
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDvina(() => ({
+ *       getToken: (opts) => inject(AuthService).getAccessTokenSilently(opts),
+ *       language: () => inject(TranslocoService).getActiveLang(),
+ *     })),
+ *   ],
+ * };
+ *
+ * // component.ts
+ * @Component({ ... })
+ * class ReportsComponent {
+ *   private sdk = inject(DvinaSdk);
+ *
+ *   // Simple signal conversion
+ *   reports = toSignal(this.sdk.reports({ first: 20 }).watch());
+ *
+ *   // Full resource with status tracking
+ *   reportResource = dvnResource({
+ *     params: () => ({ first: 20 }),
+ *     loader: ({ params }) => this.sdk.reports(params).watch(),
+ *   });
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface ToSignalOptions {
+    /**
+     * Optional DestroyRef for automatic cleanup. If not provided, `inject(DestroyRef)`
+     * is called — which requires an injection context (constructor, field initializer,
+     * or `runInInjectionContext`).
+     *
+     * Pass explicitly when calling outside an injection context.
+     *
+     * Follows the same convention as Angular's `takeUntilDestroyed()`.
+     */
+    destroyRef?: DestroyRef;
+}
+/**
+ * Convert a `DvinaQueryRef` (AsyncIterable) into a readonly Angular Signal.
+ *
+ * The signal updates automatically whenever the underlying Dexie-based SyncEngine emits new data.
+ * Cleanup (disposal of the async iterable) happens automatically when the component/service
+ * is destroyed via `DestroyRef`.
+ *
+ * Must be called in an **injection context** (field initializer, constructor,
+ * or `runInInjectionContext`) unless `options.destroyRef` is provided explicitly.
+ *
+ * @param ref - A DvinaQueryRef returned by `.watch()` on any SDK query
+ * @param options - Optional configuration
+ * @returns A readonly Signal that reflects the latest value from the query ref
+ *
+ * @example
+ * ```typescript
+ * // Field initializer (most common)
+ * reports = toSignal(this.sdk.reports({ first: 20 }).watch());
+ *
+ * // With explicit DestroyRef (for use outside injection context)
+ * const destroyRef = inject(DestroyRef);
+ * // ... later, in a method:
+ * this.reports = toSignal(ref, { destroyRef });
+ * ```
+ */
+declare function toSignal<T>(ref: DvinaQueryRef<T>, options?: ToSignalOptions): Signal<T | undefined>;
+/**
+ * Status of a {@link DvnResourceRef}.
+ *
+ * Mirrors Angular's `ResourceStatus` with the statuses relevant to
+ * Dvina SDK operations.
+ *
+ * | Status        | `value()`         | Description |
+ * |---------------|-------------------|-------------|
+ * | `'idle'`      | `undefined`       | `params` returned `undefined`; loader has not run. |
+ * | `'loading'`   | `undefined`       | Loader is running for the first time. |
+ * | `'reloading'` | Previous value    | Loader is re-running (params changed or `reload()` called). |
+ * | `'resolved'`  | Resolved value    | Loader completed successfully. |
+ * | `'error'`     | `undefined`       | Loader threw an error. |
+ */
+type DvnResourceStatus = 'idle' | 'loading' | 'reloading' | 'resolved' | 'error';
+/**
+ * The object returned by {@link dvnResource}.
+ *
+ * Provides reactive access to the loader's value, status, and error,
+ * plus imperative `reload()` and `destroy()` methods.
+ */
+interface DvnResourceRef<TResult> {
+    /** The most recently resolved value, or `undefined` while loading / on error / idle. */
+    readonly value: Signal<TResult | undefined>;
+    /** Current lifecycle status of the resource. */
+    readonly status: Signal<DvnResourceStatus>;
+    /** `true` when status is `'loading'` or `'reloading'`. */
+    readonly isLoading: Signal<boolean>;
+    /** The last error thrown by the loader, or `undefined`. */
+    readonly error: Signal<Error | undefined>;
+    /** Whether `value()` is not `undefined`. */
+    hasValue(): boolean;
+    /** Re-run the loader with the current params. Status transitions to `'reloading'`. */
+    reload(): void;
+    /** Abort / dispose any active loader and reset to `'idle'`. */
+    destroy(): void;
+}
+/**
+ * A loader function that returns either a `Promise` (one-shot fetch) or an
+ * `AsyncIterable` / `DvinaQueryRef` (live stream).
+ *
+ * The runtime inspects the return value:
+ * - If it has `Symbol.asyncIterator` → consumed as a stream (`for await…of`)
+ * - Otherwise → awaited as a `Promise`
+ */
+type DvnResourceLoader<TParams, TResult> = (ctx: DvnResourceLoaderCtx<TParams>) => Promise<TResult> | AsyncIterable<TResult>;
+/**
+ * Context object passed to the loader function.
+ *
+ * When the resource has `params`, `ctx.params` contains the current
+ * non-`undefined` params value. `abortSignal` can be forwarded to `fetch()`
+ * or any other cancellable API.
+ */
+interface DvnResourceLoaderCtx<TParams> {
+    /** Current params value (never `undefined`). Only present when `params` is configured. */
+    params: TParams;
+    /** Aborted when params change, `reload()` is called, or the resource is destroyed. */
+    abortSignal: AbortSignal;
+}
+/**
+ * Create a Dvina resource **without reactive params**.
+ *
+ * The loader runs immediately and can be re-triggered via `reload()`.
+ *
+ * @example
+ * ```typescript
+ * config = dvnResource({
+ *   loader: () => this.sdk.config().fetch(),
+ * });
+ * ```
+ */
+declare function dvnResource<TResult>(config: {
+    params?: never;
+    loader: (ctx: {
+        abortSignal: AbortSignal;
+    }) => Promise<TResult> | AsyncIterable<TResult>;
+}): DvnResourceRef<TResult>;
+/**
+ * Create a Dvina resource **with reactive params**.
+ *
+ * The loader re-runs every time `params()` produces a new non-`undefined`
+ * value. When `params()` returns `undefined` the resource enters `'idle'`.
+ *
+ * @example
+ * ```typescript
+ * // Promise-based (one-shot fetch)
+ * userResource = dvnResource({
+ *   params: () => ({ id: this.userId() }),
+ *   loader: ({ params }) => this.sdk.user(params).fetch(),
+ * });
+ *
+ * // AsyncIterable-based (live query)
+ * reportsResource = dvnResource({
+ *   params: () => ({ first: 20 }),
+ *   loader: ({ params }) => this.sdk.reports(params).watch(),
+ * });
+ * ```
+ */
+declare function dvnResource<TParams, TResult>(config: {
+    params: () => TParams | undefined;
+    loader: (ctx: DvnResourceLoaderCtx<TParams>) => Promise<TResult> | AsyncIterable<TResult>;
+}): DvnResourceRef<TResult>;
+/**
+ * Register a singleton {@link DvinaSdk} instance in the Angular dependency injection system.
+ *
+ * Accepts either a static options object or a **factory function**. The factory
+ * variant runs inside an injection context, so Angular's `inject()` can be used
+ * to resolve auth services, language providers, and other dependencies.
+ *
+ * The SDK instance is automatically destroyed (WebSocket terminated, SSE stopped,
+ * IndexedDB closed) when the environment injector is torn down.
+ *
+ * @param optionsOrFactory - A {@link DvinaSdkOptions} object, or a factory
+ *   function that returns one. The factory is called within an injection context.
+ * @returns `EnvironmentProviders` to be added to the application config.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { provideDvina } from '@dvina/sdk/angular';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDvina(() => {
+ *       const auth = inject(AuthService);
+ *       const transloco = inject(TranslocoService);
+ *
+ *       return {
+ *         getToken: (opts) => auth.getAccessTokenSilently(opts),
+ *         language: () => transloco.getActiveLang(),
+ *       };
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Static token (scripts, tests)
+ * provideDvina({
+ *   token: 'my-static-token',
+ *   baseUrl: 'localhost:4000',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Consuming the SDK in a service
+ * import { DvinaSdk } from '@dvina/sdk';
+ *
+ * @Injectable({ providedIn: 'root' })
+ * export class ReportService {
+ *   private readonly sdk = inject(DvinaSdk);
+ *
+ *   reports = toSignal(this.sdk.reports({ first: 20 }).watch());
+ * }
+ * ```
+ */
+declare function provideDvina(optionsOrFactory: DvinaSdkOptions | (() => DvinaSdkOptions)): EnvironmentProviders;
+
+export { type DvnResourceLoader, type DvnResourceLoaderCtx, type DvnResourceRef, type DvnResourceStatus, type ToSignalOptions, dvnResource, provideDvina, toSignal };

package/dist/adapters/angular/index.js

@@ -0,0 +1,159 @@
+import { DvinaSdk } from '../../chunk-RFBLNKW6.js';
+import '../../chunk-P4BYTXZ7.js';
+import '../../chunk-PDM2KR7T.js';
+import '../../chunk-KG3GNTYI.js';
+import '../../chunk-7XBJ77RJ.js';
+import '../../chunk-7JUBGIQ2.js';
+import '../../chunk-5WRI5ZAA.js';
+import { inject, DestroyRef, signal, effect, computed, makeEnvironmentProviders, untracked } from '@angular/core';
+
+function toSignal(ref, options) {
+  const destroyRef = options?.destroyRef ?? inject(DestroyRef);
+  const sig = signal(ref.current);
+  let running = true;
+  (async () => {
+    try {
+      for await (const value of ref) {
+        if (!running) break;
+        sig.set(value);
+      }
+    } catch {
+    }
+  })();
+  destroyRef.onDestroy(() => {
+    running = false;
+    ref.dispose();
+  });
+  return sig.asReadonly();
+}
+function dvnResource(config) {
+  const destroyRef = inject(DestroyRef);
+  const hasParams = "params" in config && config.params !== void 0;
+  const _value = signal(void 0);
+  const _status = signal("idle");
+  const _error = signal(void 0);
+  let abortController = null;
+  let streamRunning = false;
+  let currentQueryRef = null;
+  const cleanup = () => {
+    abortController?.abort();
+    abortController = null;
+    streamRunning = false;
+    currentQueryRef?.dispose();
+    currentQueryRef = null;
+  };
+  const load = (params) => {
+    cleanup();
+    _error.set(void 0);
+    const hadValue = untracked(() => _value() !== void 0);
+    _status.set(hadValue ? "reloading" : "loading");
+    abortController = new AbortController();
+    const ctx = hasParams ? { params, abortSignal: abortController.signal } : { abortSignal: abortController.signal };
+    const result = config.loader(ctx);
+    if (isAsyncIterable(result)) {
+      if (hasDispose(result)) {
+        currentQueryRef = result;
+      }
+      streamRunning = true;
+      const capturedController = abortController;
+      (async () => {
+        try {
+          for await (const val of result) {
+            if (!streamRunning) break;
+            _value.set(val);
+            _status.set("resolved");
+            _error.set(void 0);
+          }
+        } catch (err) {
+          if (!streamRunning || capturedController.signal.aborted) return;
+          const wrapped = err instanceof Error ? err : new Error(String(err));
+          _error.set(wrapped);
+          _status.set("error");
+        }
+      })();
+    } else {
+      const capturedController = abortController;
+      result.then(
+        (val) => {
+          if (capturedController.signal.aborted) return;
+          _value.set(val);
+          _status.set("resolved");
+        },
+        (err) => {
+          if (capturedController.signal.aborted) return;
+          if (err instanceof DOMException && err.name === "AbortError") return;
+          const wrapped = err instanceof Error ? err : new Error(String(err));
+          _error.set(wrapped);
+          _status.set("error");
+        }
+      );
+    }
+  };
+  if (hasParams) {
+    effect(() => {
+      const params = config.params();
+      if (params !== void 0) {
+        load(params);
+      } else {
+        cleanup();
+        _value.set(void 0);
+        _status.set("idle");
+        _error.set(void 0);
+      }
+    });
+  } else {
+    load();
+  }
+  destroyRef.onDestroy(() => {
+    cleanup();
+  });
+  const status = _status.asReadonly();
+  const isLoading = computed(() => {
+    const s = _status();
+    return s === "loading" || s === "reloading";
+  });
+  return {
+    value: _value.asReadonly(),
+    status,
+    isLoading,
+    error: _error.asReadonly(),
+    hasValue: () => _value() !== void 0,
+    reload() {
+      if (hasParams) {
+        const params = config.params();
+        if (params !== void 0) {
+          load(params);
+        }
+      } else {
+        load();
+      }
+    },
+    destroy() {
+      cleanup();
+      _value.set(void 0);
+      _status.set("idle");
+      _error.set(void 0);
+    }
+  };
+}
+function isAsyncIterable(value) {
+  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function hasDispose(value) {
+  return value != null && typeof value === "object" && "dispose" in value && typeof value.dispose === "function";
+}
+function provideDvina(optionsOrFactory) {
+  return makeEnvironmentProviders([
+    {
+      provide: DvinaSdk,
+      useFactory: () => {
+        const options = typeof optionsOrFactory === "function" ? optionsOrFactory() : optionsOrFactory;
+        return new DvinaSdk(options);
+      }
+    }
+  ]);
+}
+
+export { dvnResource, provideDvina, toSignal };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/angular/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/angular/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Angular adapter for @dvina/sdk.\n *\n * Provides primitives for integrating the Dvina SDK with Angular's DI and signal system:\n *\n * - {@link provideDvina} — register a singleton `DvinaSdk` instance in the Angular DI system\n * - {@link toSignal} — lightweight converter from `DvinaQueryRef` to a readonly `Signal`\n * - {@link dvnResource} — full resource primitive inspired by Angular's `resource()` API,\n *   supporting both `Promise` and `AsyncIterable` loaders with reactive params tracking,\n *   status/error signals, and automatic cleanup.\n *\n * @example\n * ```typescript\n * import { provideDvina, toSignal, dvnResource } from '@dvina/sdk/angular';\n * import { DvinaSdk } from '@dvina/sdk';\n *\n * // app.config.ts\n * export const appConfig: ApplicationConfig = {\n *   providers: [\n *     provideDvina(() => ({\n *       getToken: (opts) => inject(AuthService).getAccessTokenSilently(opts),\n *       language: () => inject(TranslocoService).getActiveLang(),\n *     })),\n *   ],\n * };\n *\n * // component.ts\n * @Component({ ... })\n * class ReportsComponent {\n *   private sdk = inject(DvinaSdk);\n *\n *   // Simple signal conversion\n *   reports = toSignal(this.sdk.reports({ first: 20 }).watch());\n *\n *   // Full resource with status tracking\n *   reportResource = dvnResource({\n *     params: () => ({ first: 20 }),\n *     loader: ({ params }) => this.sdk.reports(params).watch(),\n *   });\n * }\n * ```\n *\n * @packageDocumentation\n */\n\nimport {\n\ttype EnvironmentProviders,\n\ttype Signal,\n\tcomputed,\n\tDestroyRef,\n\teffect,\n\tinject,\n\tmakeEnvironmentProviders,\n\tsignal,\n\tuntracked,\n} from '@angular/core';\nimport { DvinaSdk } from '../../_generated_sdk.js';\nimport type { DvinaSdkOptions } from '../../client.js';\nimport type { DvinaQueryRef } from '../../types.js';\n\nexport interface ToSignalOptions {\n\t/**\n\t * Optional DestroyRef for automatic cleanup. If not provided, `inject(DestroyRef)`\n\t * is called — which requires an injection context (constructor, field initializer,\n\t * or `runInInjectionContext`).\n\t *\n\t * Pass explicitly when calling outside an injection context.\n\t *\n\t * Follows the same convention as Angular's `takeUntilDestroyed()`.\n\t */\n\tdestroyRef?: DestroyRef;\n}\n\n/**\n * Convert a `DvinaQueryRef` (AsyncIterable) into a readonly Angular Signal.\n *\n * The signal updates automatically whenever the underlying Dexie-based SyncEngine emits new data.\n * Cleanup (disposal of the async iterable) happens automatically when the component/service\n * is destroyed via `DestroyRef`.\n *\n * Must be called in an **injection context** (field initializer, constructor,\n * or `runInInjectionContext`) unless `options.destroyRef` is provided explicitly.\n *\n * @param ref - A DvinaQueryRef returned by `.watch()` on any SDK query\n * @param options - Optional configuration\n * @returns A readonly Signal that reflects the latest value from the query ref\n *\n * @example\n * ```typescript\n * // Field initializer (most common)\n * reports = toSignal(this.sdk.reports({ first: 20 }).watch());\n *\n * // With explicit DestroyRef (for use outside injection context)\n * const destroyRef = inject(DestroyRef);\n * // ... later, in a method:\n * this.reports = toSignal(ref, { destroyRef });\n * ```\n */\nexport function toSignal<T>(ref: DvinaQueryRef<T>, options?: ToSignalOptions): Signal<T | undefined> {\n\tconst destroyRef = options?.destroyRef ?? inject(DestroyRef);\n\tconst sig = signal<T | undefined>(ref.current);\n\n\tlet running = true;\n\n\t// Consume the AsyncIterable in the background, updating the signal on each emission\n\t(async () => {\n\t\ttry {\n\t\t\tfor await (const value of ref) {\n\t\t\t\tif (!running) break;\n\t\t\t\tsig.set(value);\n\t\t\t}\n\t\t} catch {\n\t\t\t// Query ref was disposed or errored — signal keeps its last value\n\t\t}\n\t})();\n\n\t// Cleanup when the Angular component/service is destroyed\n\tdestroyRef.onDestroy(() => {\n\t\trunning = false;\n\t\tref.dispose();\n\t});\n\n\treturn sig.asReadonly();\n}\n\n// ---------------------------------------------------------------------------\n// dvnResource\n// ---------------------------------------------------------------------------\n\n/**\n * Status of a {@link DvnResourceRef}.\n *\n * Mirrors Angular's `ResourceStatus` with the statuses relevant to\n * Dvina SDK operations.\n *\n * | Status        | `value()`         | Description |\n * |---------------|-------------------|-------------|\n * | `'idle'`      | `undefined`       | `params` returned `undefined`; loader has not run. |\n * | `'loading'`   | `undefined`       | Loader is running for the first time. |\n * | `'reloading'` | Previous value    | Loader is re-running (params changed or `reload()` called). |\n * | `'resolved'`  | Resolved value    | Loader completed successfully. |\n * | `'error'`     | `undefined`       | Loader threw an error. |\n */\nexport type DvnResourceStatus = 'idle' | 'loading' | 'reloading' | 'resolved' | 'error';\n\n/**\n * The object returned by {@link dvnResource}.\n *\n * Provides reactive access to the loader's value, status, and error,\n * plus imperative `reload()` and `destroy()` methods.\n */\nexport interface DvnResourceRef<TResult> {\n\t/** The most recently resolved value, or `undefined` while loading / on error / idle. */\n\treadonly value: Signal<TResult | undefined>;\n\t/** Current lifecycle status of the resource. */\n\treadonly status: Signal<DvnResourceStatus>;\n\t/** `true` when status is `'loading'` or `'reloading'`. */\n\treadonly isLoading: Signal<boolean>;\n\t/** The last error thrown by the loader, or `undefined`. */\n\treadonly error: Signal<Error | undefined>;\n\t/** Whether `value()` is not `undefined`. */\n\thasValue(): boolean;\n\t/** Re-run the loader with the current params. Status transitions to `'reloading'`. */\n\treload(): void;\n\t/** Abort / dispose any active loader and reset to `'idle'`. */\n\tdestroy(): void;\n}\n\n/**\n * A loader function that returns either a `Promise` (one-shot fetch) or an\n * `AsyncIterable` / `DvinaQueryRef` (live stream).\n *\n * The runtime inspects the return value:\n * - If it has `Symbol.asyncIterator` → consumed as a stream (`for await…of`)\n * - Otherwise → awaited as a `Promise`\n */\nexport type DvnResourceLoader<TParams, TResult> = (\n\tctx: DvnResourceLoaderCtx<TParams>,\n) => Promise<TResult> | AsyncIterable<TResult>;\n\n/**\n * Context object passed to the loader function.\n *\n * When the resource has `params`, `ctx.params` contains the current\n * non-`undefined` params value. `abortSignal` can be forwarded to `fetch()`\n * or any other cancellable API.\n */\nexport interface DvnResourceLoaderCtx<TParams> {\n\t/** Current params value (never `undefined`). Only present when `params` is configured. */\n\tparams: TParams;\n\t/** Aborted when params change, `reload()` is called, or the resource is destroyed. */\n\tabortSignal: AbortSignal;\n}\n\n// ---- Overloads ------------------------------------------------------------\n\n/**\n * Create a Dvina resource **without reactive params**.\n *\n * The loader runs immediately and can be re-triggered via `reload()`.\n *\n * @example\n * ```typescript\n * config = dvnResource({\n *   loader: () => this.sdk.config().fetch(),\n * });\n * ```\n */\nexport function dvnResource<TResult>(config: {\n\tparams?: never;\n\tloader: (ctx: { abortSignal: AbortSignal }) => Promise<TResult> | AsyncIterable<TResult>;\n}): DvnResourceRef<TResult>;\n\n/**\n * Create a Dvina resource **with reactive params**.\n *\n * The loader re-runs every time `params()` produces a new non-`undefined`\n * value. When `params()` returns `undefined` the resource enters `'idle'`.\n *\n * @example\n * ```typescript\n * // Promise-based (one-shot fetch)\n * userResource = dvnResource({\n *   params: () => ({ id: this.userId() }),\n *   loader: ({ params }) => this.sdk.user(params).fetch(),\n * });\n *\n * // AsyncIterable-based (live query)\n * reportsResource = dvnResource({\n *   params: () => ({ first: 20 }),\n *   loader: ({ params }) => this.sdk.reports(params).watch(),\n * });\n * ```\n */\nexport function dvnResource<TParams, TResult>(config: {\n\tparams: () => TParams | undefined;\n\tloader: (ctx: DvnResourceLoaderCtx<TParams>) => Promise<TResult> | AsyncIterable<TResult>;\n}): DvnResourceRef<TResult>;\n\n// ---- Implementation -------------------------------------------------------\n\nexport function dvnResource<TParams, TResult>(config: {\n\tparams?: () => TParams | undefined;\n\tloader: (ctx: any) => Promise<TResult> | AsyncIterable<TResult>;\n}): DvnResourceRef<TResult> {\n\tconst destroyRef = inject(DestroyRef);\n\tconst hasParams = 'params' in config && config.params !== undefined;\n\n\t// Internal writable signals\n\tconst _value = signal<TResult | undefined>(undefined);\n\tconst _status = signal<DvnResourceStatus>('idle');\n\tconst _error = signal<Error | undefined>(undefined);\n\n\t// Cleanup handles\n\tlet abortController: AbortController | null = null;\n\tlet streamRunning = false;\n\tlet currentQueryRef: { dispose(): void } | null = null;\n\n\t/**\n\t * Cancel any in-flight loader (Promise abort + AsyncIterable dispose).\n\t */\n\tconst cleanup = () => {\n\t\tabortController?.abort();\n\t\tabortController = null;\n\t\tstreamRunning = false;\n\t\tcurrentQueryRef?.dispose();\n\t\tcurrentQueryRef = null;\n\t};\n\n\t/**\n\t * Run the loader for the given params.\n\t */\n\tconst load = (params?: Exclude<TParams, undefined>) => {\n\t\tcleanup();\n\t\t_error.set(undefined);\n\n\t\tconst hadValue = untracked(() => _value() !== undefined);\n\t\t_status.set(hadValue ? 'reloading' : 'loading');\n\n\t\tabortController = new AbortController();\n\t\tconst ctx = hasParams\n\t\t\t? { params: params!, abortSignal: abortController.signal }\n\t\t\t: { abortSignal: abortController.signal };\n\n\t\tconst result = config.loader(ctx);\n\n\t\tif (isAsyncIterable(result)) {\n\t\t\t// --- Stream mode (AsyncIterable / DvinaQueryRef) ---\n\t\t\t// Keep a reference for disposal if it quacks like a DvinaQueryRef\n\t\t\tif (hasDispose(result)) {\n\t\t\t\tcurrentQueryRef = result;\n\t\t\t}\n\n\t\t\tstreamRunning = true;\n\t\t\tconst capturedController = abortController;\n\n\t\t\t(async () => {\n\t\t\t\ttry {\n\t\t\t\t\tfor await (const val of result) {\n\t\t\t\t\t\tif (!streamRunning) break;\n\t\t\t\t\t\t_value.set(val);\n\t\t\t\t\t\t_status.set('resolved');\n\t\t\t\t\t\t_error.set(undefined);\n\t\t\t\t\t}\n\t\t\t\t} catch (err: unknown) {\n\t\t\t\t\tif (!streamRunning || capturedController.signal.aborted) return;\n\t\t\t\t\tconst wrapped = err instanceof Error ? err : new Error(String(err));\n\t\t\t\t\t_error.set(wrapped);\n\t\t\t\t\t_status.set('error');\n\t\t\t\t}\n\t\t\t})();\n\t\t} else {\n\t\t\t// --- Promise mode (one-shot) ---\n\t\t\tconst capturedController = abortController;\n\n\t\t\t(result as Promise<TResult>).then(\n\t\t\t\t(val) => {\n\t\t\t\t\tif (capturedController.signal.aborted) return;\n\t\t\t\t\t_value.set(val);\n\t\t\t\t\t_status.set('resolved');\n\t\t\t\t},\n\t\t\t\t(err: unknown) => {\n\t\t\t\t\tif (capturedController.signal.aborted) return;\n\t\t\t\t\tif (err instanceof DOMException && err.name === 'AbortError') return;\n\t\t\t\t\tconst wrapped = err instanceof Error ? err : new Error(String(err));\n\t\t\t\t\t_error.set(wrapped);\n\t\t\t\t\t_status.set('error');\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\t};\n\n\t// ---- Reactive params tracking (same pattern as yokaResource) ----\n\n\tif (hasParams) {\n\t\teffect(() => {\n\t\t\tconst params = config.params!();\n\n\t\t\tif (params !== undefined) {\n\t\t\t\tload(params as Exclude<TParams, undefined>);\n\t\t\t} else {\n\t\t\t\tcleanup();\n\t\t\t\t_value.set(undefined);\n\t\t\t\t_status.set('idle');\n\t\t\t\t_error.set(undefined);\n\t\t\t}\n\t\t});\n\t} else {\n\t\t// No params — run immediately\n\t\tload();\n\t}\n\n\t// Auto-cleanup on destroy\n\tdestroyRef.onDestroy(() => {\n\t\tcleanup();\n\t});\n\n\t// ---- Public API ----\n\n\tconst status = _status.asReadonly();\n\tconst isLoading = computed(() => {\n\t\tconst s = _status();\n\t\treturn s === 'loading' || s === 'reloading';\n\t});\n\n\treturn {\n\t\tvalue: _value.asReadonly(),\n\t\tstatus,\n\t\tisLoading,\n\t\terror: _error.asReadonly(),\n\t\thasValue: () => _value() !== undefined,\n\n\t\treload() {\n\t\t\tif (hasParams) {\n\t\t\t\tconst params = config.params!();\n\t\t\t\tif (params !== undefined) {\n\t\t\t\t\tload(params as Exclude<TParams, undefined>);\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tload();\n\t\t\t}\n\t\t},\n\n\t\tdestroy() {\n\t\t\tcleanup();\n\t\t\t_value.set(undefined);\n\t\t\t_status.set('idle');\n\t\t\t_error.set(undefined);\n\t\t},\n\t};\n}\n\n// ---- Type guards ----------------------------------------------------------\n\nfunction isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {\n\treturn value != null && typeof value === 'object' && Symbol.asyncIterator in value;\n}\n\nfunction hasDispose(value: unknown): value is { dispose(): void } {\n\treturn (\n\t\tvalue != null && typeof value === 'object' && 'dispose' in value && typeof (value as any).dispose === 'function'\n\t);\n}\n\n// ---------------------------------------------------------------------------\n// provideDvina\n// ---------------------------------------------------------------------------\n\n/**\n * Register a singleton {@link DvinaSdk} instance in the Angular dependency injection system.\n *\n * Accepts either a static options object or a **factory function**. The factory\n * variant runs inside an injection context, so Angular's `inject()` can be used\n * to resolve auth services, language providers, and other dependencies.\n *\n * The SDK instance is automatically destroyed (WebSocket terminated, SSE stopped,\n * IndexedDB closed) when the environment injector is torn down.\n *\n * @param optionsOrFactory - A {@link DvinaSdkOptions} object, or a factory\n *   function that returns one. The factory is called within an injection context.\n * @returns `EnvironmentProviders` to be added to the application config.\n *\n * @example\n * ```typescript\n * // app.config.ts\n * import { provideDvina } from '@dvina/sdk/angular';\n *\n * export const appConfig: ApplicationConfig = {\n *   providers: [\n *     provideDvina(() => {\n *       const auth = inject(AuthService);\n *       const transloco = inject(TranslocoService);\n *\n *       return {\n *         getToken: (opts) => auth.getAccessTokenSilently(opts),\n *         language: () => transloco.getActiveLang(),\n *       };\n *     }),\n *   ],\n * };\n * ```\n *\n * @example\n * ```typescript\n * // Static token (scripts, tests)\n * provideDvina({\n *   token: 'my-static-token',\n *   baseUrl: 'localhost:4000',\n * })\n * ```\n *\n * @example\n * ```typescript\n * // Consuming the SDK in a service\n * import { DvinaSdk } from '@dvina/sdk';\n *\n * @Injectable({ providedIn: 'root' })\n * export class ReportService {\n *   private readonly sdk = inject(DvinaSdk);\n *\n *   reports = toSignal(this.sdk.reports({ first: 20 }).watch());\n * }\n * ```\n */\nexport function provideDvina(optionsOrFactory: DvinaSdkOptions | (() => DvinaSdkOptions)): EnvironmentProviders {\n\treturn makeEnvironmentProviders([\n\t\t{\n\t\t\tprovide: DvinaSdk,\n\t\t\tuseFactory: () => {\n\t\t\t\tconst options = typeof optionsOrFactory === 'function' ? optionsOrFactory() : optionsOrFactory;\n\t\t\t\treturn new DvinaSdk(options);\n\t\t\t},\n\t\t},\n\t]);\n}\n"]}

package/dist/adapters/react/index.cjs

@@ -0,0 +1,51 @@
+'use strict';
+
+require('../../chunk-DZUJEN5N.cjs');
+var react = require('react');
+
+function useLiveQuery(factory, deps) {
+  const ref = react.useMemo(factory, deps);
+  const [value, setValue] = react.useState(ref.current);
+  if (process.env.NODE_ENV !== "production") {
+    const changeCount = react.useRef(0);
+    const lastChangeTime = react.useRef(Date.now());
+    const now = Date.now();
+    if (ref !== void 0) {
+      const elapsed = now - lastChangeTime.current;
+      if (elapsed < 1e3) {
+        changeCount.current++;
+      } else {
+        changeCount.current = 1;
+      }
+      lastChangeTime.current = now;
+      if (changeCount.current > 10) {
+        console.warn(
+          "useLiveQuery: query ref was recreated more than 10 times within 1 second. This usually means the dependency array is unstable (e.g. a new object/array created every render). Ensure deps contain only primitive values or stable references."
+        );
+        changeCount.current = 0;
+      }
+    }
+  }
+  react.useEffect(() => {
+    let active = true;
+    setValue(ref.current);
+    (async () => {
+      try {
+        for await (const v of ref) {
+          if (!active) break;
+          setValue(v);
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      active = false;
+      ref.dispose();
+    };
+  }, [ref]);
+  return value;
+}
+
+exports.useLiveQuery = useLiveQuery;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/adapters/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/react/index.ts"],"names":["useMemo","useState","useRef","useEffect"],"mappings":";;;;;AA2DO,SAAS,YAAA,CAAgB,SAAiC,IAAA,EAAyC;AAEzG,EAAA,MAAM,GAAA,GAAMA,aAAA,CAAQ,OAAA,EAAS,IAAI,CAAA;AAEjC,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAIC,cAAA,CAAwB,IAAI,OAAO,CAAA;AAG7D,EAAA,IAAI,OAAA,CAAQ,GAAA,CAAI,QAAA,KAAa,YAAA,EAAc;AAE1C,IAAA,MAAM,WAAA,GAAcC,aAAO,CAAC,CAAA;AAE5B,IAAA,MAAM,cAAA,GAAiBA,YAAA,CAAO,IAAA,CAAK,GAAA,EAAK,CAAA;AAExC,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,IAAI,QAAQ,MAAA,EAAW;AACtB,MAAA,MAAM,OAAA,GAAU,MAAM,cAAA,CAAe,OAAA;AACrC,MAAA,IAAI,UAAU,GAAA,EAAM;AACnB,QAAA,WAAA,CAAY,OAAA,EAAA;AAAA,MACb,CAAA,MAAO;AACN,QAAA,WAAA,CAAY,OAAA,GAAU,CAAA;AAAA,MACvB;AACA,MAAA,cAAA,CAAe,OAAA,GAAU,GAAA;AAEzB,MAAA,IAAI,WAAA,CAAY,UAAU,EAAA,EAAI;AAC7B,QAAA,OAAA,CAAQ,IAAA;AAAA,UACP;AAAA,SAGD;AACA,QAAA,WAAA,CAAY,OAAA,GAAU,CAAA;AAAA,MACvB;AAAA,IACD;AAAA,EACD;AAEA,EAAAC,eAAA,CAAU,MAAM;AACf,IAAA,IAAI,MAAA,GAAS,IAAA;AAGb,IAAA,QAAA,CAAS,IAAI,OAAO,CAAA;AAEpB,IAAA,CAAC,YAAY;AACZ,MAAA,IAAI;AACH,QAAA,WAAA,MAAiB,KAAK,GAAA,EAAK;AAC1B,UAAA,IAAI,CAAC,MAAA,EAAQ;AACb,UAAA,QAAA,CAAS,CAAC,CAAA;AAAA,QACX;AAAA,MACD,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACD,CAAA,GAAG;AAEH,IAAA,OAAO,MAAM;AACZ,MAAA,MAAA,GAAS,KAAA;AACT,MAAA,GAAA,CAAI,OAAA,EAAQ;AAAA,IACb,CAAA;AAAA,EACD,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AAER,EAAA,OAAO,KAAA;AACR","file":"index.cjs","sourcesContent":["/**\n * React adapter for @dvina/sdk.\n *\n * Converts DvinaQueryRef (AsyncIterable) into React state via hooks.\n *\n * @example\n * ```tsx\n * import { useLiveQuery } from '@dvina/sdk/react';\n *\n * function ReportsPage() {\n *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);\n *   return (\n *     <ul>\n *       {reports?.nodes.map(r => <li key={r.id}>{r.name}</li>)}\n *     </ul>\n *   );\n * }\n * ```\n *\n * @packageDocumentation\n */\n\nimport { useState, useEffect, useMemo, useRef } from 'react';\nimport type { DvinaQueryRef } from '../../types.js';\n\n/**\n * React hook that subscribes to a `DvinaQueryRef` (AsyncIterable) and\n * returns its latest value as React state.\n *\n * Accepts a **factory function** that creates the query ref, along with a\n * dependency array. The factory is memoized internally — the ref is only\n * recreated when the dependencies change, preventing infinite\n * dispose-subscribe loops that would occur with inline `.watch()` calls.\n *\n * The component re-renders whenever the query ref emits a new value.\n * Cleanup (disposal of the subscription) happens automatically when the\n * component unmounts or when dependencies change.\n *\n * @param factory - A function that returns a DvinaQueryRef (e.g. `() => sdk.reports().watch()`)\n * @param deps - Dependency array controlling when the ref is recreated (same semantics as `useMemo`)\n * @returns The latest value from the query ref, or `undefined` if not yet loaded\n *\n * @example\n * ```tsx\n * // Static query — ref created once\n * function ReportsPage() {\n *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);\n *   if (!reports) return <div>Loading...</div>;\n *   return <ul>{reports.nodes.map(r => <li key={r.id}>{r.name}</li>)}</ul>;\n * }\n *\n * // Reactive query — ref recreated when `id` changes\n * function ReportDetail({ id }: { id: string }) {\n *   const report = useLiveQuery(() => sdk.report({ id }).watch(), [id]);\n *   if (!report) return <div>Loading...</div>;\n *   return <h1>{report.name}</h1>;\n * }\n * ```\n */\nexport function useLiveQuery<T>(factory: () => DvinaQueryRef<T>, deps: readonly unknown[]): T | undefined {\n\t// eslint-disable-next-line react-hooks/exhaustive-deps -- deps are forwarded from the caller\n\tconst ref = useMemo(factory, deps);\n\n\tconst [value, setValue] = useState<T | undefined>(ref.current);\n\n\t// Track rapid ref changes in dev mode to warn about missing deps\n\tif (process.env.NODE_ENV !== 'production') {\n\t\t// eslint-disable-next-line react-hooks/rules-of-hooks -- dev-only, always runs in dev\n\t\tconst changeCount = useRef(0);\n\t\t// eslint-disable-next-line react-hooks/rules-of-hooks\n\t\tconst lastChangeTime = useRef(Date.now());\n\n\t\tconst now = Date.now();\n\t\tif (ref !== undefined) {\n\t\t\tconst elapsed = now - lastChangeTime.current;\n\t\t\tif (elapsed < 1000) {\n\t\t\t\tchangeCount.current++;\n\t\t\t} else {\n\t\t\t\tchangeCount.current = 1;\n\t\t\t}\n\t\t\tlastChangeTime.current = now;\n\n\t\t\tif (changeCount.current > 10) {\n\t\t\t\tconsole.warn(\n\t\t\t\t\t'useLiveQuery: query ref was recreated more than 10 times within 1 second. ' +\n\t\t\t\t\t\t'This usually means the dependency array is unstable (e.g. a new object/array ' +\n\t\t\t\t\t\t'created every render). Ensure deps contain only primitive values or stable references.',\n\t\t\t\t);\n\t\t\t\tchangeCount.current = 0;\n\t\t\t}\n\t\t}\n\t}\n\n\tuseEffect(() => {\n\t\tlet active = true;\n\n\t\t// Sync initial value in case it changed between render and effect\n\t\tsetValue(ref.current);\n\n\t\t(async () => {\n\t\t\ttry {\n\t\t\t\tfor await (const v of ref) {\n\t\t\t\t\tif (!active) break;\n\t\t\t\t\tsetValue(v);\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Query ref was disposed or errored — state keeps its last value\n\t\t\t}\n\t\t})();\n\n\t\treturn () => {\n\t\t\tactive = false;\n\t\t\tref.dispose();\n\t\t};\n\t}, [ref]);\n\n\treturn value;\n}\n"]}

package/dist/adapters/react/index.d.cts

@@ -0,0 +1,62 @@
+import { D as DvinaQueryRef } from '../../types-2RotD0Ab.cjs';
+import 'graphql';
+
+/**
+ * React adapter for @dvina/sdk.
+ *
+ * Converts DvinaQueryRef (AsyncIterable) into React state via hooks.
+ *
+ * @example
+ * ```tsx
+ * import { useLiveQuery } from '@dvina/sdk/react';
+ *
+ * function ReportsPage() {
+ *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);
+ *   return (
+ *     <ul>
+ *       {reports?.nodes.map(r => <li key={r.id}>{r.name}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * React hook that subscribes to a `DvinaQueryRef` (AsyncIterable) and
+ * returns its latest value as React state.
+ *
+ * Accepts a **factory function** that creates the query ref, along with a
+ * dependency array. The factory is memoized internally — the ref is only
+ * recreated when the dependencies change, preventing infinite
+ * dispose-subscribe loops that would occur with inline `.watch()` calls.
+ *
+ * The component re-renders whenever the query ref emits a new value.
+ * Cleanup (disposal of the subscription) happens automatically when the
+ * component unmounts or when dependencies change.
+ *
+ * @param factory - A function that returns a DvinaQueryRef (e.g. `() => sdk.reports().watch()`)
+ * @param deps - Dependency array controlling when the ref is recreated (same semantics as `useMemo`)
+ * @returns The latest value from the query ref, or `undefined` if not yet loaded
+ *
+ * @example
+ * ```tsx
+ * // Static query — ref created once
+ * function ReportsPage() {
+ *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);
+ *   if (!reports) return <div>Loading...</div>;
+ *   return <ul>{reports.nodes.map(r => <li key={r.id}>{r.name}</li>)}</ul>;
+ * }
+ *
+ * // Reactive query — ref recreated when `id` changes
+ * function ReportDetail({ id }: { id: string }) {
+ *   const report = useLiveQuery(() => sdk.report({ id }).watch(), [id]);
+ *   if (!report) return <div>Loading...</div>;
+ *   return <h1>{report.name}</h1>;
+ * }
+ * ```
+ */
+declare function useLiveQuery<T>(factory: () => DvinaQueryRef<T>, deps: readonly unknown[]): T | undefined;
+
+export { useLiveQuery };

package/dist/adapters/react/index.d.ts

@@ -0,0 +1,62 @@
+import { D as DvinaQueryRef } from '../../types-2RotD0Ab.js';
+import 'graphql';
+
+/**
+ * React adapter for @dvina/sdk.
+ *
+ * Converts DvinaQueryRef (AsyncIterable) into React state via hooks.
+ *
+ * @example
+ * ```tsx
+ * import { useLiveQuery } from '@dvina/sdk/react';
+ *
+ * function ReportsPage() {
+ *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);
+ *   return (
+ *     <ul>
+ *       {reports?.nodes.map(r => <li key={r.id}>{r.name}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * React hook that subscribes to a `DvinaQueryRef` (AsyncIterable) and
+ * returns its latest value as React state.
+ *
+ * Accepts a **factory function** that creates the query ref, along with a
+ * dependency array. The factory is memoized internally — the ref is only
+ * recreated when the dependencies change, preventing infinite
+ * dispose-subscribe loops that would occur with inline `.watch()` calls.
+ *
+ * The component re-renders whenever the query ref emits a new value.
+ * Cleanup (disposal of the subscription) happens automatically when the
+ * component unmounts or when dependencies change.
+ *
+ * @param factory - A function that returns a DvinaQueryRef (e.g. `() => sdk.reports().watch()`)
+ * @param deps - Dependency array controlling when the ref is recreated (same semantics as `useMemo`)
+ * @returns The latest value from the query ref, or `undefined` if not yet loaded
+ *
+ * @example
+ * ```tsx
+ * // Static query — ref created once
+ * function ReportsPage() {
+ *   const reports = useLiveQuery(() => sdk.reports({ first: 20 }).watch(), []);
+ *   if (!reports) return <div>Loading...</div>;
+ *   return <ul>{reports.nodes.map(r => <li key={r.id}>{r.name}</li>)}</ul>;
+ * }
+ *
+ * // Reactive query — ref recreated when `id` changes
+ * function ReportDetail({ id }: { id: string }) {
+ *   const report = useLiveQuery(() => sdk.report({ id }).watch(), [id]);
+ *   if (!report) return <div>Loading...</div>;
+ *   return <h1>{report.name}</h1>;
+ * }
+ * ```
+ */
+declare function useLiveQuery<T>(factory: () => DvinaQueryRef<T>, deps: readonly unknown[]): T | undefined;
+
+export { useLiveQuery };