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

package/src/index.ts

@@ -0,0 +1,365 @@
+import type { SyncedDbConfig } from './types';
+import {
+  Sp00kyClient,
+  type Sp00kyQueryResultPromise,
+  type AuthService,
+  type BucketHandle,
+  type UpdateOptions,
+  type RunOptions,
+  type SyncHealth,
+  type StorageHealth,
+  type PreloadOptions,
+  type PreloadRefresh,
+} from '@spooky-sync/core';
+
+import type {
+  GetTable,
+  QueryBuilder,
+  SchemaStructure,
+  TableModel,
+  TableNames,
+  QueryResult,
+  RelatedFieldsMap,
+  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, type Surreal } from 'surrealdb';
+export { RecordId, Uuid };
+export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
+export { createQuery, useQuery, type CreateQueryResult, type QueryOptions } from './lib/create-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 { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
+export { useDb, usePendingMutations } from './lib/context';
+export { createSubmission, type Submission } from './lib/create-submission';
+export { conflate } from './lib/conflate';
+export { fromSubscription } from './lib/from-subscription';
+
+// Re-export query builder types for convenience
+export type {
+  QueryModifier,
+  QueryModifierBuilder,
+  QueryInfo,
+  RelationshipsMetadata,
+  RelationshipDefinition,
+  InferRelatedModelFromMetadata,
+  GetCardinality,
+  GetTable,
+  TableModel,
+  TableNames,
+  QueryResult,
+};
+
+export type RelationshipField<
+  Schema extends SchemaStructure,
+  TableName extends TableNames<Schema>,
+  Field extends RelationshipFieldsFromSchema<Schema, TableName>,
+> = GetRelationship<Schema, TableName, Field>;
+
+export type RelatedFieldsTableScoped<
+  Schema extends SchemaStructure,
+  TableName extends TableNames<Schema>,
+  RelatedFields extends RelationshipFieldsFromSchema<Schema, TableName> =
+    RelationshipFieldsFromSchema<Schema, TableName>,
+> = {
+  [K in RelatedFields]: {
+    to: RelationshipField<Schema, TableName, K>['to'];
+    relatedFields: RelatedFieldsMap;
+    cardinality: RelationshipField<Schema, TableName, K>['cardinality'];
+  };
+};
+
+export type InferModel<
+  Schema extends SchemaStructure,
+  TableName extends TableNames<Schema>,
+  RelatedFields extends RelatedFieldsTableScoped<Schema, TableName>,
+> = QueryResult<Schema, TableName, RelatedFields, true>;
+
+export type WithRelated<Field extends string, RelatedFields extends RelatedFieldsMap = {}> = {
+  [K in Field]: Omit<RelatedFieldMapEntry, 'relatedFields'> & {
+    relatedFields: RelatedFields;
+  };
+};
+
+export type WithRelatedMany<Field extends string, RelatedFields extends RelatedFieldsMap = {}> = {
+  [K in Field]: {
+    to: Field;
+    relatedFields: RelatedFields;
+    cardinality: 'many';
+  };
+};
+
+/**
+ * SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration.
+ * Delegates all logic to the underlying sp00ky-ts instance.
+ *
+ * NOTE: keep in sync with packages/client-solid/src/index.ts (SyncedDb).
+ * Copied rather than shared so this package's dependency graph never pulls
+ * in solid-js 1.x; fold the two together once client-solid moves to Solid 2.
+ */
+export class SyncedDb<S extends SchemaStructure> {
+  private config: SyncedDbConfig<S>;
+  private sp00ky: Sp00kyClient<S> | null = null;
+  private _initialized = false;
+
+  constructor(config: SyncedDbConfig<S>) {
+    this.config = config;
+  }
+
+  public getSp00ky(): Sp00kyClient<S> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky;
+  }
+
+  /**
+   * Initialize the sp00ky-ts instance
+   */
+  async init(): Promise<void> {
+    if (this._initialized) return;
+    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.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.create(id, payload as Record<string, unknown>);
+  }
+
+  /**
+   * Update an existing record in the database
+   */
+  async update<TName extends TableNames<S>>(
+    tableName: TName,
+    recordId: string,
+    payload: Partial<TableModel<GetTable<S, TName>>>,
+    options?: UpdateOptions
+  ): Promise<void> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.update(
+      tableName as string,
+      recordId,
+      payload as Record<string, unknown>,
+      options
+    );
+  }
+
+  /**
+   * Delete an existing record in the database
+   */
+  async delete<TName extends TableNames<S>>(
+    tableName: TName,
+    selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>
+  ): Promise<void> {
+    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; Solid 2 store proxies serve methods BOUND, so a RecordId read out
+    // of a query row reports 'bound RecordId' — accept both.)
+    const ctorName = (selector as any)?.constructor?.name;
+    const isRecordId =
+      selector instanceof RecordId || ctorName === 'RecordId' || ctorName === 'bound 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 `createQuery` 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);
+  }
+
+  /**
+   * Query data from the database
+   */
+  public query<TName extends TableNames<S>>(
+    table: TName
+  ): 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>>(
+    backend: B,
+    path: R,
+    payload: RoutePayload<S, B, R>,
+    options?: RunOptions
+  ): Promise<void> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.run(backend, path, payload, options);
+  }
+
+  /**
+   * Sign out, clear session and local storage
+   */
+  public async signOut(): Promise<void> {
+    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.sp00ky) throw new Error('SyncedDb not initialized');
+    return await this.sp00ky.useRemote(fn);
+  }
+  /**
+   * Access the remote database service directly
+   */
+  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(): 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.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.auth;
+  }
+
+  get pendingMutationCount(): number {
+    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.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.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.bucket(name);
+  }
+
+  getBucketConfig(name: string): BucketDefinitionSchema | undefined {
+    return this.config.schema.buckets?.find((b) => b.name === name);
+  }
+}
+
+export * from './types';

package/src/lib/Sp00kyProvider.ts

@@ -0,0 +1,104 @@
+import type { Element } from 'solid-js';
+import {
+  createSignal,
+  onSettled,
+  onCleanup,
+  createComponent,
+  createMemo,
+  merge,
+} from 'solid-js';
+import type { SchemaStructure } from '@spooky-sync/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?: 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: Element;
+}
+
+export function Sp00kyProvider<S extends SchemaStructure>(
+  props: Sp00kyProviderProps<S>
+): Element {
+  const merged = merge({ fallback: undefined as Element | undefined }, props);
+
+  // Written from the async init continuation — outside any tracking scope.
+  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined, { ownedWrite: true });
+
+  // Init 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;
+  });
+
+  // `onSettled` replaces Solid 1's `onMount`.
+  onSettled(() => {
+    void (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;
+    // Solid 2: the context object IS the provider component.
+    return createComponent(Sp00kyContext, {
+      value: instance,
+      get children() {
+        return merged.children;
+      },
+    });
+  });
+
+  return content as unknown as Element;
+}

package/src/lib/__tests__/conflate.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { createEffect, createRoot, flush } from 'solid-js';
+import { conflate } from '../conflate';
+import { fromSubscription } from '../from-subscription';
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+describe('conflate', () => {
+  it('delivers values pushed after a pull is parked', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => (cb = undefined);
+    })[Symbol.asyncIterator]();
+
+    const p = it.next();
+    cb!(1);
+    expect(await p).toEqual({ value: 1, done: false });
+  });
+
+  it('conflates: only the newest unconsumed value survives', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => (cb = undefined);
+    })[Symbol.asyncIterator]();
+
+    cb!(1);
+    cb!(2);
+    cb!(3);
+    expect(await it.next()).toEqual({ value: 3, done: false });
+  });
+
+  it('return() unsubscribes and resolves a parked pull as done', async () => {
+    let unsubscribed = false;
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => {
+        unsubscribed = true;
+        cb = undefined;
+      };
+    })[Symbol.asyncIterator]();
+
+    const parked = it.next();
+    await it.return!();
+    await tick();
+    expect(unsubscribed).toBe(true);
+    expect(await parked).toEqual({ value: undefined, done: true });
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+
+  it('supports async subscribe (unsubscribe still runs after return())', async () => {
+    let unsubscribed = false;
+    const it = conflate<number>(async () => {
+      await tick();
+      return () => {
+        unsubscribed = true;
+      };
+    })[Symbol.asyncIterator]();
+
+    await it.return!();
+    await tick();
+    await tick();
+    expect(unsubscribed).toBe(true);
+  });
+
+  it('values pushed after return() are dropped', async () => {
+    let cb: ((v: number) => void) | undefined;
+    const it = conflate<number>((c) => {
+      cb = c;
+      return () => {};
+    })[Symbol.asyncIterator]();
+    await it.return!();
+    cb!(42);
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+});
+
+describe('fromSubscription', () => {
+  it('serves initial synchronously, then live values; unsubscribes on dispose', async () => {
+    let cb: ((v: number) => void) | undefined;
+    let unsubscribed = false;
+    const subscribe = (c: (v: number) => void) => {
+      cb = c;
+      // spooky-style: fire immediately with current value
+      c(10);
+      return () => {
+        unsubscribed = true;
+        cb = undefined;
+      };
+    };
+
+    await createRoot(async (dispose) => {
+      const v = fromSubscription(subscribe, -1);
+      const seen: number[] = [];
+      createEffect(
+        () => v(),
+        (x) => {
+          seen.push(x);
+        }
+      );
+      flush();
+      expect(v()).toBe(-1); // loadingValue readable synchronously
+      await tick();
+      flush();
+      expect(v()).toBe(10); // immediate emission landed
+
+      cb!(20);
+      await tick();
+      flush();
+      expect(v()).toBe(20);
+      expect(seen).toContain(20);
+
+      dispose();
+      await tick();
+      expect(unsubscribed).toBe(true);
+    });
+  });
+});