@spooky-sync/client-solid2 0.0.1-canary.200

package/src/lib/use-crdt-field.ts

@@ -0,0 +1,57 @@
+import { createEffect, createSignal, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { CrdtField } from '@spooky-sync/core';
+
+export function useCrdtField(
+  table: string,
+  recordId: () => string | undefined,
+  field: string,
+  fallbackText?: () => string | undefined
+): Accessor<CrdtField | null> {
+  const db = useDb();
+  const [crdtField, setCrdtField] = createSignal<CrdtField | null>(null, { ownedWrite: true });
+
+  // Two-arg Solid 2 effect: the compute tracks `recordId`, the apply owns the
+  // open/close lifecycle and returns the cleanup — which runs both when the id
+  // changes (before the next apply) and on unmount. That replaces the Solid 1
+  // version's manual currentId/initialized bookkeeping.
+  createEffect(
+    () => recordId(),
+    (id) => {
+      if (!id) {
+        setCrdtField(null);
+        return;
+      }
+      const sp00ky = db.getSp00ky();
+      let superseded = false;
+      const text = fallbackText?.();
+      sp00ky
+        .openCrdtField(table, id, field, text)
+        .then((cf) => {
+          if (!superseded) {
+            setCrdtField(cf);
+          } else {
+            sp00ky.closeCrdtField(table, id, field);
+          }
+        })
+        .catch((err) => {
+          // Silent rejections here leave the consumer's `Show when={field()}`
+          // permanently stuck on its fallback (typically a static `<p>` with
+          // no editing UI), with no error trail. Surface the failure so the
+          // root cause (missing `@crdt` annotation, schema codegen drift,
+          // local DB query failure, etc.) is visible in the console instead
+          // of silently breaking collaborative fields.
+          console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`, err);
+        });
+      return () => {
+        superseded = true;
+        if (crdtField()) {
+          sp00ky.closeCrdtField(table, id, field);
+          setCrdtField(null);
+        }
+      };
+    }
+  );
+
+  return crdtField;
+}

package/src/lib/use-download-file.ts

@@ -0,0 +1,181 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { BlobUrlLease } from '@spooky-sync/core';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface UseDownloadFileOptions {
+  /**
+   * Master switch, default `true`. `false` gives every hook instance its own
+   * private object URL fetched fresh from the bucket and revoked on unmount —
+   * no sharing, no persistence, no reuse.
+   */
+  cache?: boolean;
+  /**
+   * Keep the bytes in OPFS so they survive a reload and are available offline.
+   * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
+   * URL is still shared between components rendering the same path.
+   */
+  persist?: boolean;
+  /** Exempt this file from pressure eviction. Pinned bytes never expire. */
+  pin?: boolean;
+  /**
+   * `'never'` (default) treats a bucket path as immutable, which is how paths
+   * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
+   * to compare sizes before trusting the cached copy — for paths the app
+   * overwrites in place.
+   */
+  revalidate?: 'never' | 'head';
+}
+
+export interface UseDownloadFileResult {
+  url: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;
+}
+
+export function useDownloadFile<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
+  pathOrOptions?: Accessor<string | null | undefined> | UseDownloadFileOptions,
+  maybeOptions?: UseDownloadFileOptions
+): UseDownloadFileResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+  let path: Accessor<string | null | undefined>;
+  let options: UseDownloadFileOptions;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+    path = bucketNameOrPath as Accessor<string | null | undefined>;
+    options = (pathOrOptions as UseDownloadFileOptions) ?? {};
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    bucketName = bucketNameOrPath as BucketNames<S>;
+    path = pathOrOptions as Accessor<string | null | undefined>;
+    options = maybeOptions ?? {};
+  }
+
+  const useCache = options.cache !== false;
+
+  // Written from fetch continuations — outside any tracking scope.
+  const [url, setUrl] = createSignal<string | null>(null, { ownedWrite: true });
+  const [isLoading, setIsLoading] = createSignal(false, { ownedWrite: true });
+  const [error, setError] = createSignal<Error | null>(null, { ownedWrite: true });
+
+  // Exactly one of these is held at a time: a refcounted lease on the shared
+  // cache entry, or a private URL this instance minted and must revoke itself.
+  let lease: BlobUrlLease | null = null;
+  let privateUrl: string | null = null;
+
+  const [refetchSignal, setRefetchSignal] = createSignal(0);
+  /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+  let reloadOnce = false;
+
+  function releaseCurrent() {
+    lease?.release();
+    lease = null;
+    if (privateUrl) {
+      URL.revokeObjectURL(privateUrl);
+      privateUrl = null;
+    }
+  }
+
+  // Two-arg Solid 2 effect: compute tracks path + refetch tick; apply runs the
+  // fetch and returns the cancel/release cleanup, which runs before the next
+  // apply and on unmount.
+  createEffect(
+    () => {
+      refetchSignal();
+      return path();
+    },
+    (filePath) => {
+      releaseCurrent();
+
+      if (!filePath) {
+        setUrl(null);
+        setIsLoading(false);
+        setError(null);
+        return;
+      }
+
+      const reload = reloadOnce;
+      reloadOnce = false;
+
+      let cancelled = false;
+      setIsLoading(true);
+      setError(null);
+
+      const bucket = db.bucket(bucketName);
+      const resolve = useCache
+        ? bucket
+            .url(filePath, {
+              persist: options.persist !== false,
+              pin: options.pin,
+              revalidate: options.revalidate,
+              reload,
+            })
+            .then((acquired) => {
+              if (!acquired) return null;
+              if (cancelled) {
+                // Unmounted or the path changed mid-flight — hand the reference
+                // straight back, or the entry never drops to zero and its object
+                // URL leaks for the life of the tab.
+                acquired.release();
+                return null;
+              }
+              lease = acquired;
+              return acquired.url;
+            })
+        : bucket.read(filePath, { persist: false, reload: true }).then((blob) => {
+            if (!blob || cancelled) return null;
+            privateUrl = URL.createObjectURL(blob);
+            return privateUrl;
+          });
+
+      resolve.then(
+        (result) => {
+          if (!cancelled) {
+            setUrl(result);
+            setIsLoading(false);
+          }
+          return undefined;
+        },
+        (err) => {
+          if (!cancelled) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsLoading(false);
+          }
+        }
+      );
+
+      return () => {
+        cancelled = true;
+      };
+    }
+  );
+
+  onCleanup(() => {
+    releaseCurrent();
+  });
+
+  const refetch = () => {
+    reloadOnce = true;
+    setRefetchSignal((n) => n + 1);
+  };
+
+  return { url, isLoading, error, refetch };
+}

package/src/lib/use-feature-flag.ts

@@ -0,0 +1,43 @@
+import type { Accessor } from 'solid-js';
+import { onCleanup } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+import type { FeatureFlagOptions } from '@spooky-sync/core';
+
+export interface UseFeatureFlag {
+  variant: Accessor<string | undefined>;
+  payload: Accessor<unknown | undefined>;
+  enabled: Accessor<boolean>;
+}
+
+/**
+ * Subscribe to a feature flag for the currently authenticated user.
+ *
+ * Returns three Solid accessors that update reactively whenever the
+ * server-materialized assignment in `_00_user_feature` changes. Backed by
+ * the same SSP + sync pipeline that powers `createQuery`, so toggling a flag
+ * via `spky flag enable <key>` propagates to the UI without a refresh.
+ *
+ * `enabled()` is `true` when the resolved variant exists and is not 'off'.
+ * For multi-variant flags, prefer `variant()` directly.
+ */
+export function useFeatureFlag(key: string, options?: FeatureFlagOptions): UseFeatureFlag {
+  const db = useDb();
+  const handle = db.getSp00ky().feature(key, options);
+  onCleanup(() => handle.close());
+
+  const state = fromSubscription<{ variant: string | undefined; payload: unknown }>(
+    (cb) =>
+      handle.subscribe((s) => cb({ variant: s.variant ?? options?.fallback, payload: s.payload })),
+    { variant: handle.variant(), payload: handle.payload() }
+  );
+
+  return {
+    variant: () => state().variant,
+    payload: () => state().payload,
+    enabled: () => {
+      const v = state().variant;
+      return v !== undefined && v !== 'off';
+    },
+  };
+}

package/src/lib/use-file-upload.ts

@@ -0,0 +1,146 @@
+import { createSignal, onCleanup } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import { fileToUint8Array } from '@spooky-sync/core';
+import type { BucketPutOptions, BucketPutResult } from '@spooky-sync/core';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface FileUploadResult {
+  isUploading: () => boolean;
+  error: () => Error | null;
+  clearError: () => void;
+  upload: (
+    path: string,
+    file: File | Blob,
+    options?: BucketPutOptions
+  ) => Promise<BucketPutResult | void>;
+  download: (path: string) => Promise<string | null>;
+  remove: (path: string) => Promise<void>;
+  exists: (path: string) => Promise<boolean>;
+}
+
+export function useFileUpload<S extends SchemaStructure>(
+  bucketName: BucketNames<S>
+): FileUploadResult;
+export function useFileUpload<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>
+): FileUploadResult;
+export function useFileUpload<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  maybeBucketName?: BucketNames<S>
+): FileUploadResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    // oxlint-disable-next-line no-non-null-assertion
+    bucketName = maybeBucketName!;
+  }
+
+  // Written from async continuations — outside any tracking scope.
+  const [isUploading, setIsUploading] = createSignal(false, { ownedWrite: true });
+  const [error, setError] = createSignal<Error | null>(null, { ownedWrite: true });
+
+  const objectUrls: string[] = [];
+  onCleanup(() => {
+    for (const url of objectUrls) {
+      URL.revokeObjectURL(url);
+    }
+  });
+
+  const clearError = () => setError(null);
+
+  const validate = (file: File | Blob): void => {
+    const config = db.getBucketConfig(bucketName as string);
+    if (!config) return;
+
+    if (config.maxSize !== null && config.maxSize !== undefined && file.size > config.maxSize) {
+      const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
+      throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
+    }
+
+    if (config.allowedExtensions && config.allowedExtensions.length > 0) {
+      const fileName = (file as File).name;
+      if (fileName) {
+        const ext = fileName.split('.').pop()?.toLowerCase();
+        if (!ext || !config.allowedExtensions.includes(ext)) {
+          throw new Error(
+            `File type not allowed. Accepted: ${config.allowedExtensions.join(', ')}.`
+          );
+        }
+      }
+    }
+  };
+
+  const upload = async (
+    path: string,
+    file: File | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult | void> => {
+    setError(null);
+    try {
+      validate(file);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return;
+    }
+
+    setIsUploading(true);
+    try {
+      const bytes = await fileToUint8Array(file);
+      return await db.bucket(bucketName).put(path, bytes, options);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    } finally {
+      setIsUploading(false);
+    }
+  };
+
+  const download = async (path: string): Promise<string | null> => {
+    setError(null);
+    try {
+      const content = await db.bucket(bucketName).get(path);
+      if (!content) return null;
+      const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
+      objectUrls.push(objectUrl);
+      return objectUrl;
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return null;
+    }
+  };
+
+  const remove = async (path: string): Promise<void> => {
+    setError(null);
+    try {
+      await db.bucket(bucketName).delete(path);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    }
+  };
+
+  const exists = async (path: string): Promise<boolean> => {
+    setError(null);
+    try {
+      return await db.bucket(bucketName).exists(path);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return false;
+    }
+  };
+
+  return {
+    isUploading,
+    error,
+    clearError,
+    upload,
+    download,
+    remove,
+    exists,
+  };
+}

package/src/lib/use-storage-status.ts

@@ -0,0 +1,44 @@
+import type { Accessor } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+import type { StorageHealth, StorageHealthStatus } from '@spooky-sync/core';
+
+export interface UseStorageStatus {
+  /** Full durability snapshot; updates reactively. */
+  health: Accessor<StorageHealth>;
+  /** `'unknown'` | `'persistent'` | `'memory'`. */
+  status: Accessor<StorageHealthStatus>;
+  /** `true` when the local store survives a reload. */
+  isPersistent: Accessor<boolean>;
+  /**
+   * `true` only when durable storage was requested and could NOT be opened, so
+   * the dataset is sitting in RAM and local writes die on reload. Drive a
+   * warning off this, not off `status`: a store configured as in-memory reports
+   * `'memory'` too, and that is a choice rather than a problem.
+   */
+  isMemoryFallback: Accessor<boolean>;
+}
+
+/**
+ * Observe how durable the LOCAL cache is, for a "no local storage" warning.
+ *
+ * Under `localEngine: 'sqlite'` with `store: 'indexeddb'` the durable store is
+ * the OPFS SAHPool VFS, and only ONE client per bucket can hold it open: a
+ * second tab of the same app cannot get it and runs in memory instead (the
+ * engine retries first, so a closing tab's lock is usually waited out). Must be
+ * used within a `<Sp00kyProvider>`.
+ */
+export function useStorageStatus(): UseStorageStatus {
+  const db = useDb();
+  const health = fromSubscription<StorageHealth>(
+    (cb) => db.subscribeToStorageHealth(cb),
+    db.storageHealth
+  );
+
+  return {
+    health,
+    status: () => health().status,
+    isPersistent: () => health().status === 'persistent',
+    isMemoryFallback: () => health().fallback,
+  };
+}

package/src/lib/use-sync-status.ts

@@ -0,0 +1,63 @@
+import type { Accessor } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+import type { ConnectionState, SyncHealth, SyncHealthStatus } from '@spooky-sync/core';
+
+export interface UseSyncStatus {
+  /** Full health snapshot; updates reactively on every transition. */
+  health: Accessor<SyncHealth>;
+  /** `'healthy'` | `'degraded'`. */
+  status: Accessor<SyncHealthStatus>;
+  isHealthy: Accessor<boolean>;
+  /** `true` once sync has failed for a sustained run — drive a banner off this. */
+  isDegraded: Accessor<boolean>;
+  /** `true` once at least one sync round has succeeded this session. */
+  everConnected: Accessor<boolean>;
+  /**
+   * `true` only for a real lost connection: degraded AFTER a first successful
+   * sync. Stays `false` during the initial "connecting" phase (degraded but
+   * never reached the server yet), so an indicator can show nothing until the
+   * app has actually connected once.
+   */
+  isOffline: Accessor<boolean>;
+  /**
+   * Transport state of the remote WebSocket. Flips the instant the socket
+   * drops, unlike `status`, which only degrades after a sustained run of failed
+   * sync rounds — so this is what to drive a "reconnecting…" affordance off.
+   */
+  connection: Accessor<ConnectionState>;
+  /**
+   * `true` while the connection is being re-established. Usually still
+   * `isHealthy()`: a short reconnect is invisible to sync, and writes made
+   * during it are queued locally and pushed once the socket is back.
+   */
+  isReconnecting: Accessor<boolean>;
+}
+
+/**
+ * Observe sync health for a "can't reach the server" banner / indicator.
+ *
+ * Backed by `db.subscribeToSyncHealth`. Individual sync failures (a transient
+ * remote 500 on query registration, a dropped socket) are absorbed by the
+ * retry and never flip this; `isDegraded()` only goes true once failures
+ * persist for the configured number of consecutive rounds (sp00ky core config
+ * `syncHealth.degradeAfterConsecutiveFailures`, default 3), and flips back on
+ * the next successful round. Must be used within a `<Sp00kyProvider>`.
+ */
+export function useSyncStatus(): UseSyncStatus {
+  const db = useDb();
+  // The subscription fires synchronously with the current status; the initial
+  // value (loadingValue) just avoids a flash before it lands.
+  const health = fromSubscription<SyncHealth>((cb) => db.subscribeToSyncHealth(cb), db.syncHealth);
+
+  return {
+    health,
+    status: () => health().status,
+    isHealthy: () => health().status === 'healthy',
+    isDegraded: () => health().status === 'degraded',
+    everConnected: () => health().everConnected,
+    isOffline: () => health().status === 'degraded' && health().everConnected,
+    connection: () => health().connection,
+    isReconnecting: () => health().connection === 'reconnecting',
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,83 @@
+import type { SyncedDb } from '../index';
+import type { GenericSchema } from '../lib/models';
+import type { Sp00kyConfig } from '@spooky-sync/core';
+import type { SchemaStructure, TableNames, GetTable, TableModel } from '@spooky-sync/query-builder';
+
+/**
+ * Options for database provisioning
+ */
+export interface ProvisionOptions {
+  /** Force re-provision even if schema already exists */
+  force?: boolean;
+}
+
+declare global {
+  interface Window {
+    db?: SyncedDb<any>;
+  }
+}
+
+export type CacheStrategy = 'memory' | 'indexeddb';
+
+/**
+ * Infer Schema type (Record<TableName, Model>) from schema const
+ */
+export type InferSchemaFromConst<S extends SchemaStructure> = {
+  [K in TableNames<S>]: TableModel<GetTable<S, K>>;
+};
+
+/**
+ * Infer Relationships type from schema const's relationships array
+ * Converts from array format to nested object format
+ */
+export type InferRelationshipsFromConst<S extends SchemaStructure, Schema extends GenericSchema> = {
+  [TableName in TableNames<S>]: {
+    [Rel in Extract<S['relationships'][number], { from: TableName }> as Rel['field']]: {
+      model: Rel['to'] extends keyof Schema ? Schema[Rel['to']] : any;
+      table: Rel['to'];
+      cardinality: Rel['cardinality'];
+    };
+  };
+};
+
+// Prettify helper expands types for better intellisense
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+export type SyncedDbConfig<S extends SchemaStructure> = Prettify<Sp00kyConfig<S>>;
+
+// export interface LocalDbConfig {
+//   name: string;
+//   storageStrategy: CacheStrategy;
+//   namespace?: string;
+//   database?: string;
+// }
+
+// export interface RemoteDbConfig {
+//   url: string;
+//   token?: string;
+//   namespace?: string;
+//   database?: string;
+// }
+
+// export interface DbConnection {
+//   internal: Surreal;
+//   local: Surreal;
+//   remote?: Surreal;
+// }
+
+// export interface SyncStatus {
+//   isConnected: boolean;
+//   lastSync?: Date;
+//   pendingChanges: number;
+//   localRecords: number;
+//   remoteRecords?: number;
+// }
+
+// export interface SyncOptions {
+//   /** Force full sync regardless of last sync time */
+//   force?: boolean;
+//   /** Sync only specific tables */
+//   tables?: string[];
+//   /** Batch size for sync operations */
+//   batchSize?: number;
+// }

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "outDir": "./dist",
+    "paths": {
+      "@spooky-sync/query-builder": ["../query-builder/src/index.ts"],
+      "@spooky-sync/core": ["../core/src/index.ts"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  external: [
+    'surrealdb',
+    '@surrealdb/wasm',
+    'solid-js',
+    '@spooky-sync/core',
+    '@spooky-sync/query-builder',
+  ],
+  clean: true,
+  hash: false,
+  sourcemap: true,
+  target: 'es2020',
+});

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // solid-js's `node` export condition resolves the SSR build, where user
+  // effects intentionally never run. Force the browser dev build so tests
+  // exercise real client-side reactivity semantics.
+  resolve: {
+    conditions: ['browser', 'development'],
+  },
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});