@spooky-sync/client-solid2 0.0.1-alpha.1

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-activity.ts

@@ -0,0 +1,99 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import { fromSubscription } from './from-subscription';
+import type { SyncedDb } from '../index';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+
+export interface UseSyncActivityOptions {
+  /**
+   * How long queries must be fetching before `isDownloading()` turns on.
+   * Filters the sub-frame fetches a warm cache produces, so the indicator only
+   * shows work the user could notice. Default 200 ms.
+   */
+  downloadDelayMs?: number;
+  /**
+   * `isUploading()` turns on once MORE than this many mutations are waiting in
+   * the outbox. Default 1: a single write acknowledged within a round trip is
+   * not worth an animation; a backlog is.
+   */
+  uploadThreshold?: number;
+}
+
+export interface UseSyncActivity {
+  /** Queries inside a fetch cycle right now (core `fetchingQueryCount`). */
+  fetchingQueries: Accessor<number>;
+  /** Locally committed writes the server has not acknowledged yet. */
+  pendingMutations: Accessor<number>;
+  /** Fetching for longer than `downloadDelayMs`. Drives a "downloading" mark. */
+  isDownloading: Accessor<boolean>;
+  /** More than `uploadThreshold` writes queued. Drives an "uploading" mark. */
+  isUploading: Accessor<boolean>;
+}
+
+/**
+ * The two directions of sync traffic, for an indicator in the app chrome.
+ *
+ * `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+ * not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+ * is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+ * local-first page that answers from cache and confirms with the server in a
+ * few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+ * pass the `SyncedDb` explicitly.
+ */
+export function useSyncActivity<S extends SchemaStructure = any>(
+  dbOrOptions?: SyncedDb<S> | UseSyncActivityOptions,
+  maybeOptions?: UseSyncActivityOptions
+): UseSyncActivity {
+  const explicitDb =
+    dbOrOptions && typeof (dbOrOptions as SyncedDb<S>).subscribeToFetchActivity === 'function'
+      ? (dbOrOptions as SyncedDb<S>)
+      : undefined;
+  const options = (explicitDb ? maybeOptions : (dbOrOptions as UseSyncActivityOptions)) ?? {};
+  const db = explicitDb ?? useDb<S>();
+  const downloadDelayMs = options.downloadDelayMs ?? 200;
+  const uploadThreshold = options.uploadThreshold ?? 1;
+
+  const fetchingQueries = fromSubscription<number>(
+    (cb) => db.subscribeToFetchActivity(cb),
+    db.fetchingQueryCount
+  );
+  const pendingMutations = fromSubscription<number>(
+    (cb) => db.subscribeToPendingMutations(cb),
+    db.pendingMutationCount
+  );
+
+  // ON after the delay, OFF immediately. Written from a timer, hence ownedWrite.
+  const [isDownloading, setIsDownloading] = createSignal(false, { ownedWrite: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  createEffect(
+    () => fetchingQueries() > 0,
+    (busy) => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      if (!busy) {
+        setIsDownloading(false);
+        return;
+      }
+      if (downloadDelayMs <= 0) {
+        setIsDownloading(true);
+        return;
+      }
+      timer = setTimeout(() => {
+        timer = undefined;
+        setIsDownloading(true);
+      }, downloadDelayMs);
+    }
+  );
+  onCleanup(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+
+  return {
+    fetchingQueries,
+    pendingMutations,
+    isDownloading,
+    isUploading: () => pendingMutations() > uploadThreshold,
+  };
+}

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,20 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  external: [
+    'surrealdb',
+    '@surrealdb/wasm',
+    'solid-js',
+    '@solidjs/signals',
+    '@solidjs/web',
+    '@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'],
+  },
+});