@spooky-sync/client-solid 0.0.0-canary.1

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@spooky-sync/client-solid",
+  "version": "0.0.0-canary.1",
+  "type": "module",
+  "description": "SurrealDB client with local and remote database support for browser applications",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "dev:example": "pnpm build:watch",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "surrealdb",
+    "database",
+    "browser",
+    "offline",
+    "sync"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mono424/spooky.git",
+    "directory": "packages/client-solid"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "dependencies": {
+    "@spooky-sync/query-builder": "workspace:*",
+    "@spooky-sync/core": "workspace:*",
+    "@surrealdb/wasm": "^3.0.0",
+    "surrealdb": "2.0.0",
+    "valtio": "^2.1.8"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.x.x"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "solid-js": "^1.8.7",
+    "tsdown": "^0.12.4",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,41 @@
+export { SurrealDBWasmFactory } from './surrealdb-wasm-factory';
+
+import { Surreal } from 'surrealdb';
+import type { CacheStrategy } from '../types';
+
+/**
+ * Creates a SurrealDB WASM instance with the specified storage strategy
+ */
+export async function createSurrealDBWasm(
+  dbName: string,
+  strategy: CacheStrategy,
+  namespace?: string,
+  database?: string
+): Promise<Surreal> {
+  const { SurrealDBWasmFactory } = await import('./surrealdb-wasm-factory');
+  return SurrealDBWasmFactory.create(dbName, strategy, namespace, database);
+}
+
+/**
+ * Creates a memory-based SurrealDB WASM instance
+ */
+export async function createMemoryDB(
+  dbName: string,
+  namespace?: string,
+  database?: string
+): Promise<Surreal> {
+  const { SurrealDBWasmFactory } = await import('./surrealdb-wasm-factory');
+  return SurrealDBWasmFactory.createMemory(dbName, namespace, database);
+}
+
+/**
+ * Creates an IndexedDB-based SurrealDB WASM instance
+ */
+export async function createIndexedDBDatabase(
+  dbName: string,
+  namespace?: string,
+  database?: string
+): Promise<Surreal> {
+  const { SurrealDBWasmFactory } = await import('./surrealdb-wasm-factory');
+  return SurrealDBWasmFactory.createIndexedDB(dbName, namespace, database);
+}

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

@@ -0,0 +1,64 @@
+import { Diagnostic, 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') {
+    console.log(`[SurrealDB_WASM] [${key}] ${type}:${phase}\n${JSON.stringify(other, null, 2)}`);
+  }
+};
+
+/**
+ * SurrealDB WASM client factory for different storage strategies
+ */
+export class SurrealDBWasmFactory {
+  /**
+   * Creates a SurrealDB WASM instance with the specified storage strategy
+   */
+  static async create(
+    dbName: string,
+    strategy: CacheStrategy,
+    namespace?: string,
+    database?: string
+  ): Promise<Surreal> {
+    // Create Surreal instance with WASM engines
+    const surreal = new Surreal({
+      engines: applyDiagnostics(createWasmEngines(), printDiagnostic),
+    });
+
+    // Connect to the appropriate storage backend
+    const connectionUrl = strategy === 'indexeddb' ? `indxdb://${dbName}` : 'mem://';
+
+    await surreal.connect(connectionUrl);
+
+    // Set namespace and database
+    await surreal.use({
+      namespace: namespace || 'main',
+      database: database || dbName,
+    });
+
+    return surreal;
+  }
+
+  /**
+   * Creates a memory-based SurrealDB WASM instance
+   */
+  static async createMemory(
+    dbName: string,
+    namespace?: string,
+    database?: string
+  ): Promise<Surreal> {
+    return this.create(dbName, 'memory', namespace, database);
+  }
+
+  /**
+   * Creates an IndexedDB-based SurrealDB WASM instance
+   */
+  static async createIndexedDB(
+    dbName: string,
+    namespace?: string,
+    database?: string
+  ): Promise<Surreal> {
+    return this.create(dbName, 'indexeddb', namespace, database);
+  }
+}

package/src/index.ts

@@ -0,0 +1,254 @@
+import type { SyncedDbConfig } from './types';
+import {
+  SpookyClient,
+  AuthService,
+  type SpookyQueryResultPromise,
+  UpdateOptions,
+  RunOptions,
+} from '@spooky-sync/core';
+
+import {
+  GetTable,
+  QueryBuilder,
+  SchemaStructure,
+  TableModel,
+  TableNames,
+  QueryResult,
+  RelatedFieldsMap,
+  RelationshipFieldsFromSchema,
+  GetRelationship,
+  RelatedFieldMapEntry,
+  InnerQuery,
+  BackendNames,
+  BackendRoutes,
+  RoutePayload,
+} from '@spooky-sync/query-builder';
+
+import { RecordId, Uuid, Surreal } from 'surrealdb';
+export { RecordId, Uuid };
+export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
+export { useQuery } from './lib/use-query';
+export { SpookyProvider, type SpookyProviderProps } from './lib/SpookyProvider';
+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 {
+  QueryModifier,
+  QueryModifierBuilder,
+  QueryInfo,
+  RelationshipsMetadata,
+  RelationshipDefinition,
+  InferRelatedModelFromMetadata,
+  GetCardinality,
+  GetTable,
+  TableModel,
+  TableNames,
+  QueryResult,
+} from '@spooky-sync/query-builder';
+
+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 spooky-ts for Solid.js integration
+ * Delegates all logic to the underlying spooky-ts instance
+ */
+export class SyncedDb<S extends SchemaStructure> {
+  private config: SyncedDbConfig<S>;
+  private spooky: SpookyClient<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;
+  }
+
+  /**
+   * Initialize the spooky-ts instance
+   */
+  async init(): Promise<void> {
+    if (this._initialized) return;
+    this.spooky = new SpookyClient<S>(this.config);
+    await this.spooky.init();
+    this._initialized = true;
+  }
+
+  /**
+   * 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>);
+  }
+
+  /**
+   * 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.spooky) throw new Error('SyncedDb not initialized');
+    await this.spooky.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 | 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);
+  }
+
+  /**
+   * Query data from the database
+   */
+  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, {});
+  }
+
+  /**
+   * 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.spooky) throw new Error('SyncedDb not initialized');
+    await this.spooky.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);
+    // SurrealDB authenticate returns void? or token?
+    // Assuming void or token.
+    return new RecordId('user', 'me'); // Placeholder or actual?
+  }
+
+  /**
+   * Deauthenticate from the database
+   * @deprecated Use signOut() instead
+   */
+  public async deauthenticate(): Promise<void> {
+    await this.signOut();
+  }
+
+  /**
+   * 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();
+  }
+
+  /**
+   * 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);
+  }
+  /**
+   * Access the remote database service directly
+   */
+  get remote(): SpookyClient<S>['remoteClient'] {
+    if (!this.spooky) throw new Error('SyncedDb not initialized');
+    return this.spooky.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;
+  }
+
+  /**
+   * Access the auth service
+   */
+  get auth(): AuthService<S> {
+    if (!this.spooky) throw new Error('SyncedDb not initialized');
+    return this.spooky.auth;
+  }
+
+  get pendingMutationCount(): number {
+    if (!this.spooky) throw new Error('SyncedDb not initialized');
+    return this.spooky.pendingMutationCount;
+  }
+
+  subscribeToPendingMutations(cb: (count: number) => void): () => void {
+    if (!this.spooky) throw new Error('SyncedDb not initialized');
+    return this.spooky.subscribeToPendingMutations(cb);
+  }
+}
+
+export * from './types';

package/src/lib/SpookyProvider.ts

@@ -0,0 +1,55 @@
+import { createSignal, onMount, createComponent, createMemo, JSX, mergeProps } from 'solid-js';
+import type { SchemaStructure } from '@spooky/query-builder';
+import type { SyncedDbConfig } from '../types';
+import { SyncedDb } from '../index';
+import { SpookyContext } from './context';
+
+export interface SpookyProviderProps<S extends SchemaStructure> {
+  config: SyncedDbConfig<S>;
+  fallback?: JSX.Element;
+  onError?: (error: Error) => void;
+  onReady?: (db: SyncedDb<S>) => void;
+  children: JSX.Element;
+}
+
+export function SpookyProvider<S extends SchemaStructure>(
+  props: SpookyProviderProps<S>
+): JSX.Element {
+  const merged = mergeProps(
+    {
+      fallback: undefined as JSX.Element | undefined,
+    },
+    props
+  );
+
+  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
+
+  onMount(async () => {
+    try {
+      const instance = new SyncedDb<S>(merged.config);
+      await instance.init();
+      setDb(() => instance);
+      merged.onReady?.(instance);
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      if (merged.onError) {
+        merged.onError(error);
+      } else {
+        console.error('SpookyProvider: Failed to initialize database', error);
+      }
+    }
+  });
+
+  const content = createMemo(() => {
+    const instance = db();
+    if (!instance) return merged.fallback;
+    return createComponent(SpookyContext.Provider, {
+      value: instance,
+      get children() {
+        return merged.children;
+      },
+    });
+  });
+
+  return content as unknown as JSX.Element;
+}

package/src/lib/context.ts

@@ -0,0 +1,13 @@
+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 function useDb<S extends SchemaStructure>(): SyncedDb<S> {
+  const db = useContext(SpookyContext);
+  if (!db) {
+    throw new Error('useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.');
+  }
+  return db as SyncedDb<S>;
+}

package/src/lib/models.ts

@@ -0,0 +1,8 @@
+import { RecordId } from 'surrealdb';
+
+// Re-export types from query-builder for backward compatibility
+export type { GenericModel, GenericSchema } from '@spooky/query-builder';
+
+// Model and ModelPayload types for the client
+export type Model<T> = T;
+export type ModelPayload<T> = T & { id: RecordId };

package/src/lib/use-query.ts

@@ -0,0 +1,165 @@
+import {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+  QueryResult,
+} from '@spooky-sync/query-builder';
+import { createEffect, createSignal, onCleanup, useContext } from 'solid-js';
+import { SyncedDb } from '..';
+import { SpookyQueryResultPromise } from '@spooky-sync/core';
+import { SpookyContext } from './context';
+
+type QueryArg<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+> =
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+  | (() =>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+      | null
+      | undefined);
+
+type QueryOptions = { enabled?: () => boolean };
+
+// Overload: context-based (no explicit db)
+export function useQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions,
+): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+
+// Overload: explicit db (backward-compatible)
+export function useQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  db: SyncedDb<S>,
+  finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: QueryOptions,
+): { data: () => TData | undefined; error: () => Error | undefined; isLoading: () => boolean };
+
+// Implementation
+export function useQuery<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends {
+    columns: Record<string, ColumnSchema>;
+  },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+  TData = QueryResult<S, TableName, RelatedFields, IsOne> | null,
+>(
+  dbOrQuery:
+    | SyncedDb<S>
+    | QueryArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?:
+    | QueryArg<S, TableName, T, RelatedFields, IsOne>
+    | QueryOptions,
+  maybeOptions?: QueryOptions,
+) {
+  let db: SyncedDb<S>;
+  let finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: QueryOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    // Explicit db overload: useQuery(db, query, options?)
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as QueryArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    // Context-based overload: useQuery(query, options?)
+    const contextDb = useContext(SpookyContext);
+    if (!contextDb) {
+      throw new Error(
+        'useQuery: No db argument provided and no SpookyContext found. ' +
+        'Either pass a SyncedDb instance or wrap your app in <SpookyProvider>.'
+      );
+    }
+    db = contextDb as SyncedDb<S>;
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as QueryOptions | undefined;
+  }
+
+  const [data, setData] = createSignal<TData | undefined>(undefined);
+  const [error, setError] = createSignal<Error | undefined>(undefined);
+  const [isFetched, setIsFetched] = createSignal(false);
+  const [unsubscribe, setUnsubscribe] = createSignal<(() => void) | undefined>(undefined);
+  let prevQueryString: string | undefined;
+
+  const spooky = db.getSpooky();
+
+  const initQuery = async (
+    query: FinalQuery<S, TableName, T, RelatedFields, IsOne, SpookyQueryResultPromise>
+  ) => {
+    const { hash } = await query.run();
+    setError(undefined);
+
+    const unsub = await spooky.subscribe(
+      hash,
+      (e) => {
+        const data = (query.isOne ? e[0] : e) as TData;
+        setData(() => data);
+        setIsFetched(true);
+      },
+      { immediate: true }
+    );
+
+    setUnsubscribe(() => unsub);
+  };
+
+  createEffect(() => {
+    const enabled = options?.enabled?.() ?? true;
+
+    // If disabled, clear error and don't run query
+    if (!enabled) {
+      setError(undefined);
+      return;
+    }
+
+    // Init Query
+    const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+    if (!query) {
+      return;
+    }
+
+    // Prevent re-running if query hasn't changed
+    const queryString = JSON.stringify(query);
+    if (queryString === prevQueryString) {
+      return;
+    }
+    prevQueryString = queryString;
+
+    // Reset fetched state when query changes
+    setIsFetched(false);
+    initQuery(query);
+
+    // Cleanup
+    onCleanup(() => {
+      unsubscribe?.();
+    });
+  });
+
+  const isLoading = () => {
+    return !isFetched() && error() === undefined;
+  };
+
+  return {
+    data,
+    error,
+    isLoading,
+  };
+}