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

package/src/index.ts

@@ -0,0 +1,410 @@
+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';
+import { snapshot } from 'solid-js';
+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 {
+  useSyncActivity,
+  type UseSyncActivity,
+  type UseSyncActivityOptions,
+} from './lib/use-sync-activity';
+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 { useBlurhash, type UseBlurhashResult } from './lib/use-blurhash';
+export {
+  useBucketImage,
+  type UseBucketImageOptions,
+  type UseBucketImageResult,
+} from './lib/use-bucket-image';
+export { Blurhash, type BlurhashProps } from './lib/Blurhash';
+export { BucketImage, type BucketImageProps } from './lib/BucketImage';
+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.
+ * Solid-2-only differences: `delete` accepts 'bound RecordId', and write
+ * payloads go through `snapshot()` (see `unproxy` below).
+ */
+
+/**
+ * Solid 2 stores wrap every object read out of them (query rows, their nested
+ * arrays, `createStore` docs) in a Proxy. Those proxies cannot cross
+ * `postMessage` (the sqlite and shared-tabs workers): structuredClone throws
+ * DataCloneError. `snapshot()` returns the underlying plain value for store
+ * proxies and passes anything else through untouched.
+ */
+function unproxy<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  return snapshot(value as object) as T;
+}
+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, unproxy(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,
+      unproxy(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. A RecordId read out of a Solid 2 query row is a store
+    // proxy that hides its prototype (no instanceof, no constructor.name, on
+    // rc.1), so unwrap it first; cross-package RecordId instances then match
+    // by constructor name ('bound RecordId' covers rc.0 proxies).
+    const raw = unproxy(selector);
+    const ctorName = (raw as any)?.constructor?.name;
+    const isRecordId =
+      raw instanceof RecordId || ctorName === 'RecordId' || ctorName === 'bound RecordId';
+    let id: string;
+    if (typeof raw === 'string') {
+      id = raw;
+    } else if (isRecordId) {
+      id = `${tableName as string}:${(raw 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, unproxy(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);
+  }
+
+  /** Queries mid-fetch right now. See {@link useSyncActivity}. */
+  get fetchingQueryCount(): number {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.fetchingQueryCount;
+  }
+
+  /**
+   * Observe how many queries are fetching from the server. Fires immediately
+   * and on every change. Prefer the `useSyncActivity` hook in components.
+   */
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToFetchActivity(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/Blurhash.ts

@@ -0,0 +1,64 @@
+import { createEffect, type Element } from 'solid-js';
+import { decodeBlurhash } from '@spooky-sync/core';
+
+export interface BlurhashProps {
+  /** The blurhash string. Nullish paints nothing (transparent canvas). */
+  hash: string | null | undefined;
+  /** Decode resolution. 32x32 is plenty: blurhash carries at most 9x9 DCT
+   *  components, the canvas is meant to be CSS-scaled to fill. */
+  width?: number;
+  height?: number;
+  /** Contrast punch, see the blurhash reference decoder. Defaults to 1. */
+  punch?: number;
+  class?: string;
+  style?: string;
+}
+
+/**
+ * A blurhash painted onto a canvas, once per hash change. Size the canvas via
+ * `class`/`style` (e.g. `absolute inset-0 w-full h-full`); the internal decode
+ * resolution stays tiny regardless of the displayed size.
+ */
+export function Blurhash(props: BlurhashProps): Element {
+  if (typeof document === 'undefined') return null;
+  const canvas = document.createElement('canvas');
+
+  createEffect(
+    () => props.class ?? '',
+    (className) => {
+      canvas.className = className;
+    }
+  );
+  createEffect(
+    () => props.style ?? '',
+    (style) => {
+      canvas.style.cssText = style;
+    }
+  );
+
+  createEffect(
+    () => ({
+      width: props.width ?? 32,
+      height: props.height ?? 32,
+      hash: props.hash,
+      punch: props.punch ?? 1,
+    }),
+    ({ width, height, hash, punch }) => {
+      canvas.width = width;
+      canvas.height = height;
+      if (!hash) return;
+      try {
+        const pixels = decodeBlurhash(hash, width, height, punch);
+        const ctx = canvas.getContext('2d');
+        if (!ctx) return;
+        const imageData = ctx.createImageData(width, height);
+        imageData.data.set(pixels);
+        ctx.putImageData(imageData, 0, 0);
+      } catch {
+        // An invalid hash paints nothing; the layer below stays visible.
+      }
+    }
+  );
+
+  return canvas as unknown as Element;
+}

package/src/lib/BucketImage.ts

@@ -0,0 +1,170 @@
+import { createSignal, createEffect, onSettled, children, type Element } from 'solid-js';
+import type { BucketNames, SchemaStructure } from '@spooky-sync/query-builder';
+import { useBucketImage, type UseBucketImageOptions } from './use-bucket-image';
+import { Blurhash } from './Blurhash';
+
+export interface BucketImageProps {
+  /** Bucket name from the schema. */
+  bucket: string;
+  /** Path within the bucket. Nullish renders only the fallback layers. */
+  path: string | null | undefined;
+  alt?: string;
+  /** Classes for the container element (sizing/positioning). */
+  class?: string;
+  /** Classes for the inner `<img>` (the layout styles are inline). */
+  imgClass?: string;
+  /** `object-fit` for the image. Defaults to `cover`. */
+  fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+  /**
+   * Bottom placeholder layer (your own plate/skeleton), shown until the image
+   * settles. The blurhash layer paints on top of it once the sidecar resolves.
+   */
+  fallback?: Element;
+  /** Crossfade duration in ms. Defaults to 300. */
+  transition?: number;
+  /** Crossfade easing. Defaults to an ease-out-expo curve. */
+  easing?: string;
+  /** Resolve the blurhash sidecar. Defaults to true. */
+  blurhash?: boolean;
+  /** Download tuning, forwarded to the underlying `useDownloadFile`. */
+  options?: UseBucketImageOptions;
+}
+
+const LAYER_STYLE = 'position:absolute;inset:0;width:100%;height:100%;';
+
+/**
+ * A bucket image that never pops in: it layers (bottom to top) your `fallback`
+ * plate, the automatically stored blurhash, and the real image, which stays
+ * transparent until the bitmap is DECODED and then crossfades over the
+ * placeholders. Placeholder layers unmount once the fade settles. Respects
+ * prefers-reduced-motion (instant swap). The container is made
+ * `position: relative` unless your `class` positions it already.
+ *
+ * ```tsx
+ * <BucketImage bucket="covers" path={row.cover_key} class="absolute inset-0"
+ *              fallback={<MyPlate />} alt="" />
+ * ```
+ */
+export function BucketImage(props: BucketImageProps): Element {
+  if (typeof document === 'undefined') return null;
+
+  const image = useBucketImage(
+    props.bucket as BucketNames<SchemaStructure>,
+    () => props.path,
+    { ...props.options, blurhash: props.blurhash !== false }
+  );
+
+  const reducedMotion =
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  const root = document.createElement('div');
+  createEffect(
+    () => props.class ?? '',
+    (className) => {
+      root.className = className;
+    }
+  );
+  // Layers are absolutely positioned; give them an anchor without stomping on
+  // a caller class that already positions the container (inline would win).
+  onSettled(() => {
+    if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
+  });
+
+  const placeholder = document.createElement('div');
+  placeholder.style.cssText = LAYER_STYLE;
+  // Solid hands JSX props over as lazy thunks; `children` resolves them (and
+  // nested arrays/functions) to real nodes and keeps them alive reactively.
+  const fallbackHolder = document.createElement('div');
+  fallbackHolder.style.cssText = LAYER_STYLE;
+  placeholder.append(fallbackHolder);
+  const resolvedFallback = children(() => props.fallback);
+  createEffect(
+    () => resolvedFallback.toArray().filter((node) => node instanceof Node) as Node[],
+    (nodes) => {
+      fallbackHolder.replaceChildren(...nodes);
+    }
+  );
+  const hashCanvas = Blurhash({
+    get hash() {
+      return image.blurhash();
+    },
+    style: LAYER_STYLE,
+  });
+  if (hashCanvas instanceof Node) placeholder.append(hashCanvas);
+
+  const img = document.createElement('img');
+  img.decoding = 'async';
+  img.style.cssText = `${LAYER_STYLE}opacity:0;`;
+  createEffect(
+    () => props.imgClass ?? '',
+    (className) => {
+      img.className = className;
+    }
+  );
+  createEffect(
+    () => props.fit ?? 'cover',
+    (fit) => {
+      img.style.objectFit = fit;
+    }
+  );
+  createEffect(
+    () => props.alt ?? '',
+    (alt) => {
+      img.alt = alt;
+    }
+  );
+  createEffect(
+    () =>
+      reducedMotion
+        ? 'none'
+        : `opacity ${props.transition ?? 300}ms ${props.easing ?? 'cubic-bezier(0.16, 1, 0.3, 1)'}`,
+    (transition) => {
+      img.style.transition = transition;
+    }
+  );
+  createEffect(
+    () => image.url(),
+    (url) => {
+      if (!url) {
+        img.removeAttribute('src');
+        return;
+      }
+      img.src = url;
+      image.gate(img);
+    }
+  );
+  createEffect(
+    () => image.ready(),
+    (ready) => {
+      img.style.opacity = ready ? '1' : '0';
+    }
+  );
+
+  // Placeholders leave the DOM once the fade is over (a shelf of covers should
+  // not composite three layers each forever) and come back when the path
+  // changes mid-life (`ready` re-arms via the hook). `settled` is written from
+  // the apply phase and a timer, outside any tracking scope.
+  const [settled, setSettled] = createSignal(false, { ownedWrite: true });
+  createEffect(
+    () => ({ ready: image.ready(), transition: props.transition ?? 300 }),
+    ({ ready, transition }) => {
+      if (!ready) {
+        setSettled(false);
+        return;
+      }
+      const wait = (reducedMotion ? 0 : transition) + 120;
+      const timer = setTimeout(() => setSettled(true), wait);
+      return () => clearTimeout(timer);
+    }
+  );
+  createEffect(
+    () => settled(),
+    (isSettled) => {
+      if (isSettled) placeholder.remove();
+      else if (!placeholder.isConnected) root.insertBefore(placeholder, img);
+    }
+  );
+
+  root.append(placeholder, img);
+  return root as unknown as Element;
+}