@spooky-sync/client-solid 0.0.1-canary.18 → 0.0.1-canary.180

package/skills/{spooky-solid → sp00ky-solid}/references/file-hooks.md

@@ -7,7 +7,7 @@ Upload, download, and manage files in a SurrealDB bucket.
 ### Signatures
 
 ```typescript
-// Context-based (inside SpookyProvider)
+// Context-based (inside Sp00kyProvider)
 useFileUpload<S>(bucketName: BucketNames<S>): FileUploadResult;
 
 // Explicit db
@@ -64,11 +64,18 @@ Reactively download a file from a bucket. Re-fetches when the path changes.
 ### Signatures
 
 ```typescript
+interface UseDownloadFileOptions {
+  cache?: boolean;                    // default true — false disables every layer
+  persist?: boolean;                  // default true — keep bytes in OPFS
+  pin?: boolean;                      // exempt from pressure eviction
+  revalidate?: 'never' | 'head';      // default 'never' (paths are immutable)
+}
+
 // Context-based
 useDownloadFile<S>(
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
-  options?: { cache?: boolean },
+  options?: UseDownloadFileOptions,
 ): UseDownloadFileResult;
 
 // Explicit db
@@ -76,7 +83,7 @@ useDownloadFile<S>(
   db: SyncedDb<S>,
   bucketName: BucketNames<S>,
   path: Accessor<string | null | undefined>,
-  options?: { cache?: boolean },
+  options?: UseDownloadFileOptions,
 ): UseDownloadFileResult;
 ```
 
@@ -87,13 +94,35 @@ interface UseDownloadFileResult {
   url: Accessor<string | null>;     // Object URL for the file
   isLoading: Accessor<boolean>;
   error: Accessor<Error | null>;
-  refetch: () => void;              // Force re-download (evicts cache)
+  refetch: () => void;              // Force re-download, bypassing every layer
 }
 ```
 
 ### Caching
 
-By default, downloads are cached by `bucket:path` key with reference counting. Object URLs are revoked when no component references them. Set `cache: false` to disable.
+Three layers, checked in order:
+
+1. **Object URLs**, refcounted per `bucket:path` and shared between components. Revoked once the last holder releases and the entry ages out of a 32-entry hot window.
+2. **OPFS**, under `sp00ky-blobs/<bucketId>/<bucket>/<path>`. Survives reload, works offline, and is namespaced per signed-in user.
+3. **The bucket**, over the sync WebSocket.
+
+Nothing expires on a timer — an image whose row is still cached locally has to stay viewable offline. Bytes are dropped only when the app invalidates the path (`bucket.put`/`bucket.delete` do this automatically), when boot reconcile finds no file behind a row, or when the cache exceeds its byte budget, in which case the least-recently-used unpinned entries that nothing is rendering go first.
+
+Configure with `blobCache: { enabled, maxBytes, clearOnSignOut }` on the client. The budget defaults to `min(512 MB, quota × 0.25)`. Inspect live numbers in the DevTools Storage tab under "Bucket file cache".
+
+`persist: false` keeps the in-tab sharing but writes nothing durable. `cache: false` gives each hook instance a private URL fetched fresh and revoked on unmount.
+
+A bucket path is treated as immutable, which is how paths are normally written (`crypto.randomUUID() + ext`). If your app overwrites a path in place from another device, pass `revalidate: 'head'` — it spends a remote `head()` to compare sizes before trusting the cached copy, and keeps the cached copy when that call fails so going offline never blanks an image.
+
+### Pinning and prefetching
+
+```tsx
+const bucket = db.bucket('avatars');
+await bucket.prefetch(paths);   // warm the cache for offline use
+bucket.pin('logo.png');         // never evicted under pressure
+bucket.unpin('logo.png');
+await bucket.evict('old.png');  // drop locally, leave the remote file alone
+```
 
 ### Example
 

package/src/cache/index.ts

@@ -1,6 +1,6 @@
 export { SurrealDBWasmFactory } from './surrealdb-wasm-factory';
 
-import { Surreal } from 'surrealdb';
+import type { Surreal } from 'surrealdb';
 import type { CacheStrategy } from '../types';
 
 /**

package/src/cache/surrealdb-wasm-factory.ts

@@ -1,9 +1,11 @@
-import { Diagnostic, Surreal, applyDiagnostics } from 'surrealdb';
+import type { Diagnostic} from 'surrealdb';
+import { Surreal, applyDiagnostics } from 'surrealdb';
 import { createWasmEngines } from '@surrealdb/wasm';
 import type { CacheStrategy } from '../types';
 
 const printDiagnostic = ({ key, type, phase, ...other }: Diagnostic) => {
   if (phase === 'progress' || phase === 'after') {
+    // oxlint-disable-next-line no-console -- intentional diagnostic logging
     console.log(`[SurrealDB_WASM] [${key}] ${type}:${phase}\n${JSON.stringify(other, null, 2)}`);
   }
 };
@@ -11,6 +13,7 @@ const printDiagnostic = ({ key, type, phase, ...other }: Diagnostic) => {
 /**
  * SurrealDB WASM client factory for different storage strategies
  */
+// oxlint-disable-next-line no-extraneous-class -- factory pattern groups related static methods
 export class SurrealDBWasmFactory {
   /**
    * Creates a SurrealDB WASM instance with the specified storage strategy

package/src/index.ts

@@ -1,14 +1,18 @@
 import type { SyncedDbConfig } from './types';
 import {
-  SpookyClient,
-  AuthService,
-  BucketHandle,
-  type SpookyQueryResultPromise,
-  UpdateOptions,
-  RunOptions,
+  Sp00kyClient,
+  type Sp00kyQueryResultPromise,
+  type AuthService,
+  type BucketHandle,
+  type UpdateOptions,
+  type RunOptions,
+  type SyncHealth,
+  type StorageHealth,
+  type PreloadOptions,
+  type PreloadRefresh,
 } from '@spooky-sync/core';
 
-import {
+import type {
   GetTable,
   QueryBuilder,
   SchemaStructure,
@@ -19,25 +23,55 @@ import {
   RelationshipFieldsFromSchema,
   GetRelationship,
   RelatedFieldMapEntry,
+  FinalQuery,
   InnerQuery,
   BackendNames,
   BackendRoutes,
   RoutePayload,
   BucketNames,
   BucketDefinitionSchema,
+  QueryModifier,
+  QueryModifierBuilder,
+  QueryInfo,
+  RelationshipsMetadata,
+  RelationshipDefinition,
+  InferRelatedModelFromMetadata,
+  GetCardinality,
 } from '@spooky-sync/query-builder';
 
-import { RecordId, Uuid, Surreal } from 'surrealdb';
+import { RecordId, Uuid, type Surreal } from 'surrealdb';
 export { RecordId, Uuid };
 export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
 export { useQuery } from './lib/use-query';
+export { createPreload } from './lib/create-preload';
+export type { PreloadOptions, PreloadRefresh } from '@spooky-sync/core';
+export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
+export type {
+  SyncHealth,
+  SyncHealthStatus,
+  SyncHealthConfig,
+  ConnectionState,
+  ReconnectConfig,
+} from '@spooky-sync/core';
+export { useStorageStatus, type UseStorageStatus } from './lib/use-storage-status';
+export type { StorageHealth, StorageHealthStatus } from '@spooky-sync/core';
+export { useCrdtField } from './lib/use-crdt-field';
+export { useFeatureFlag, type UseFeatureFlag } from './lib/use-feature-flag';
+export {
+  useAppRelease,
+  type UseAppRelease,
+  type UseAppReleaseOptions,
+} from './lib/use-app-release';
 export { useFileUpload, type FileUploadResult } from './lib/use-file-upload';
-export { useDownloadFile, type UseDownloadFileOptions, type UseDownloadFileResult } from './lib/use-download-file';
-export { SpookyProvider, type SpookyProviderProps } from './lib/SpookyProvider';
+export {
+  useDownloadFile,
+  type UseDownloadFileOptions,
+  type UseDownloadFileResult,
+} from './lib/use-download-file';
+export { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
 export { useDb } from './lib/context';
 
 // export { AuthEventTypes } from "@spooky-sync/core"; // TODO: Verify if AuthEventTypes exists in core
-export type {};
 
 // Re-export query builder types for convenience
 export type {
@@ -52,7 +86,7 @@ export type {
   TableModel,
   TableNames,
   QueryResult,
-} from '@spooky-sync/query-builder';
+};
 
 export type RelationshipField<
   Schema extends SchemaStructure,
@@ -94,39 +128,52 @@ export type WithRelatedMany<Field extends string, RelatedFields extends RelatedF
 };
 
 /**
- * SyncedDb - A thin wrapper around spooky-ts for Solid.js integration
- * Delegates all logic to the underlying spooky-ts instance
+ * SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration
+ * Delegates all logic to the underlying sp00ky-ts instance
  */
 export class SyncedDb<S extends SchemaStructure> {
   private config: SyncedDbConfig<S>;
-  private spooky: SpookyClient<S> | null = null;
+  private sp00ky: Sp00kyClient<S> | null = null;
   private _initialized = false;
 
   constructor(config: SyncedDbConfig<S>) {
     this.config = config;
   }
 
-  public getSpooky(): SpookyClient<S> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky;
+  public getSp00ky(): Sp00kyClient<S> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky;
   }
 
   /**
-   * Initialize the spooky-ts instance
+   * Initialize the sp00ky-ts instance
    */
   async init(): Promise<void> {
     if (this._initialized) return;
-    this.spooky = new SpookyClient<S>(this.config);
-    await this.spooky.init();
+    this.sp00ky = new Sp00kyClient<S>(this.config);
+    await this.sp00ky.init();
     this._initialized = true;
   }
 
+  /**
+   * Tear down the client: leaves the tabs broker, closes the local store and
+   * remote socket, and frees the wasm circuit. Without this a remounted provider
+   * (or an HMR reload) strands a whole client, and the abandoned wasm heaps stay
+   * resident because V8 cannot see how much wasm memory a dropped wrapper holds.
+   */
+  async close(): Promise<void> {
+    const instance = this.sp00ky;
+    this.sp00ky = null;
+    this._initialized = false;
+    if (instance) await instance.close();
+  }
+
   /**
    * Create a new record in the database
    */
   async create(id: string, payload: Record<string, unknown>): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.create(id, payload as Record<string, unknown>);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.create(id, payload as Record<string, unknown>);
   }
 
   /**
@@ -138,8 +185,8 @@ export class SyncedDb<S extends SchemaStructure> {
     payload: Partial<TableModel<GetTable<S, TName>>>,
     options?: UpdateOptions
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.update(
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.update(
       tableName as string,
       recordId,
       payload as Record<string, unknown>,
@@ -152,12 +199,39 @@ export class SyncedDb<S extends SchemaStructure> {
    */
   async delete<TName extends TableNames<S>>(
     tableName: TName,
-    selector: string | InnerQuery<GetTable<S, TName>, boolean>
+    selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    if (typeof selector !== 'string')
-      throw new Error('Only string ID selectors are supported currently with core');
-    await this.spooky.delete(tableName as string, selector);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    // Accept a `"table:id"` string OR a RecordId — live-query rows carry their
+    // `id` as a RecordId, so callers can pass `db.delete('game', row.id)`
+    // directly. Build the canonical string from the raw id part (not
+    // `RecordId.toString()`, which escapes special chars) so it round-trips
+    // through the engine's `parseRecordIdString`. InnerQuery selectors are not
+    // supported yet. (cross-package RecordId instances → match by constructor name.)
+    const isRecordId =
+      selector instanceof RecordId || (selector as any)?.constructor?.name === 'RecordId';
+    let id: string;
+    if (typeof selector === 'string') {
+      id = selector;
+    } else if (isRecordId) {
+      id = `${tableName as string}:${(selector as RecordId).id}`;
+    } else {
+      throw new Error('Only string ID or RecordId selectors are supported currently with core');
+    }
+    await this.sp00ky.delete(tableName as string, id);
+  }
+
+  /**
+   * Preload/prewarm a built query into the local cache without registering a
+   * live view. Fetches once and stores the rows (+ embedded related children)
+   * locally so a later `useQuery` for the same data paints instantly. Best-effort.
+   */
+  public async preload(
+    finalQuery: FinalQuery<S, any, any, any, any, Sp00kyQueryResultPromise>,
+    options?: PreloadOptions
+  ): Promise<void> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.preload(finalQuery, options);
   }
 
   /**
@@ -165,34 +239,31 @@ export class SyncedDb<S extends SchemaStructure> {
    */
   public query<TName extends TableNames<S>>(
     table: TName
-  ): QueryBuilder<S, TName, SpookyQueryResultPromise, {}, false> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.query(table, {});
+  ): QueryBuilder<S, TName, Sp00kyQueryResultPromise, {}, false> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.query(table, {});
   }
 
   /**
    * Run a backend operation
    */
-  public async run<
-    B extends BackendNames<S>,
-    R extends BackendRoutes<S, B>,
-  >(
+  public async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
     backend: B,
     path: R,
     payload: RoutePayload<S, B, R>,
-    options?: RunOptions,
+    options?: RunOptions
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.run(backend, path, payload, options);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.run(backend, path, payload, options);
   }
 
   /**
    * Authenticate with the database
    */
   public async authenticate(token: string): Promise<RecordId<string>> {
-    const result = await this.spooky?.authenticate(token);
-    // SpookyClient.authenticate returns whatever remote.authenticate returns (boolean or token usually?)
-    // Wait, checked SpookyClient: return this.remote.getClient().authenticate(token);
+    await this.sp00ky?.authenticate(token);
+    // Sp00kyClient.authenticate returns whatever remote.authenticate returns (boolean or token usually?)
+    // Wait, checked Sp00kyClient: return this.remote.getClient().authenticate(token);
     // SurrealDB authenticate returns void? or token?
     // Assuming void or token.
     return new RecordId('user', 'me'); // Placeholder or actual?
@@ -210,54 +281,92 @@ export class SyncedDb<S extends SchemaStructure> {
    * Sign out, clear session and local storage
    */
   public async signOut(): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.auth.signOut();
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.auth.signOut();
   }
 
   /**
    * Execute a function with direct access to the remote database connection
    */
   public async useRemote<T>(fn: (db: Surreal) => T | Promise<T>): Promise<T> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return await this.spooky.useRemote(fn);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return await this.sp00ky.useRemote(fn);
   }
   /**
    * Access the remote database service directly
    */
-  get remote(): SpookyClient<S>['remoteClient'] {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.remoteClient;
+  get remote(): Sp00kyClient<S>['remoteClient'] {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.remoteClient;
   }
 
   /**
    * Access the local database service directly
    */
-  get local(): SpookyClient<S>['localClient'] {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.localClient;
+  get local(): Sp00kyClient<S>['localClient'] {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.localClient;
   }
 
   /**
    * Access the auth service
    */
   get auth(): AuthService<S> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.auth;
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.auth;
   }
 
   get pendingMutationCount(): number {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.pendingMutationCount;
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.pendingMutationCount;
+  }
+
+  /** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+  get liveRetryCount(): number {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.liveRetryCount;
   }
 
   subscribeToPendingMutations(cb: (count: number) => void): () => void {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.subscribeToPendingMutations(cb);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToPendingMutations(cb);
+  }
+
+  /** Current sync-health snapshot. See {@link useSyncStatus}. */
+  get syncHealth(): SyncHealth {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.syncHealth;
+  }
+
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
+   * components; this is the imperative escape hatch.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToSyncHealth(cb);
+  }
+
+  /** Current local-store durability snapshot. See {@link useStorageStatus}. */
+  get storageHealth(): StorageHealth {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.storageHealth;
+  }
+
+  /**
+   * Observe local-store durability. Fires immediately with the current snapshot
+   * and again on change. Prefer the `useStorageStatus` hook in components; this
+   * is the imperative escape hatch.
+   */
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToStorageHealth(cb);
   }
 
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.bucket(name);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.bucket(name);
   }
 
   getBucketConfig(name: string): BucketDefinitionSchema | undefined {

package/src/lib/Sp00kyProvider.ts

@@ -0,0 +1,104 @@
+import type { JSX } from 'solid-js';
+import {
+  createSignal,
+  onMount,
+  onCleanup,
+  createComponent,
+  createMemo,
+  mergeProps,
+} from 'solid-js';
+import type { SchemaStructure } from '@spooky/query-builder';
+import type { SyncedDbConfig } from '../types';
+import { SyncedDb } from '../index';
+import { Sp00kyContext } from './context';
+
+export interface Sp00kyProviderProps<S extends SchemaStructure> {
+  config: SyncedDbConfig<S>;
+  fallback?: JSX.Element;
+  onError?: (error: Error) => void;
+  onReady?: (db: SyncedDb<S>) => void;
+  /**
+   * Prewarm data into the local cache before revealing the UI. Runs after
+   * `init()`; the `fallback` stays visible until it resolves. Use awaitable
+   * `db.preload(...)` calls here to gate first-load on essential data (e.g.
+   * config). On warm loads preload returns instantly, so there's no perceptible
+   * gate after the first run. Best-effort: a rejection is caught and the UI is
+   * revealed anyway.
+   */
+  preload?: (db: SyncedDb<S>) => Promise<void>;
+  children: JSX.Element;
+}
+
+export function Sp00kyProvider<S extends SchemaStructure>(
+  props: Sp00kyProviderProps<S>
+): JSX.Element {
+  const merged = mergeProps(
+    {
+      fallback: undefined as JSX.Element | undefined,
+    },
+    props
+  );
+
+  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
+
+  // `onMount` is async, so a dispose can land mid-init. Only that narrow race is
+  // handled here: an instance whose init finished AFTER the provider was already
+  // gone is closed, because nothing will ever reference it.
+  //
+  // A live, mounted client is deliberately NOT closed on cleanup. Doing that
+  // nulls `SyncedDb.sp00ky`, so every later `create`/`update`/`delete` throws
+  // "SyncedDb not initialized" while reads keep rendering from state that is
+  // already subscribed — i.e. mutations die silently and the app looks fine. In
+  // a host app the provider wraps the whole tree and only unmounts with the
+  // page, where the browser reclaims the worker anyway, so the leak this was
+  // meant to fix is worth far less than that risk.
+  let disposed = false;
+
+  onCleanup(() => {
+    disposed = true;
+  });
+
+  onMount(async () => {
+    try {
+      const instance = new SyncedDb<S>(merged.config);
+      await instance.init();
+      if (disposed) {
+        await instance.close();
+        return;
+      }
+      // Gate first-load UI on prewarmed data. Best-effort: never let a preload
+      // failure keep the app stuck on the fallback.
+      if (merged.preload) {
+        try {
+          await merged.preload(instance);
+        } catch (e) {
+          // oxlint-disable-next-line no-console
+          console.error('Sp00kyProvider: preload failed; revealing UI anyway', e);
+        }
+      }
+      setDb(() => instance);
+      merged.onReady?.(instance);
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      if (merged.onError) {
+        merged.onError(error);
+      } else {
+        // oxlint-disable-next-line no-console
+        console.error('Sp00kyProvider: Failed to initialize database', error);
+      }
+    }
+  });
+
+  const content = createMemo(() => {
+    const instance = db();
+    if (!instance) return merged.fallback;
+    return createComponent(Sp00kyContext.Provider, {
+      value: instance,
+      get children() {
+        return merged.children;
+      },
+    });
+  });
+
+  return content as unknown as JSX.Element;
+}

package/src/lib/context.ts

@@ -2,12 +2,12 @@ import { createContext, useContext } from 'solid-js';
 import type { SchemaStructure } from '@spooky/query-builder';
 import type { SyncedDb } from '../index';
 
-export const SpookyContext = createContext<SyncedDb<any> | undefined>();
+export const Sp00kyContext = createContext<SyncedDb<any> | undefined>();
 
 export function useDb<S extends SchemaStructure>(): SyncedDb<S> {
-  const db = useContext(SpookyContext);
+  const db = useContext(Sp00kyContext);
   if (!db) {
-    throw new Error('useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.');
+    throw new Error('useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.');
   }
   return db as SyncedDb<S>;
 }