@spooky-sync/core 0.0.1-canary.15 → 0.0.1-canary.151

package/src/services/database/surreal-cache-engine.ts

@@ -0,0 +1,139 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { LocalDatabaseService } from './local';
+import { resolveRelations } from './relation-resolver';
+import {
+  renderBaseSelectSurql,
+  renderRelationFetchSurql,
+} from './plan-render';
+import type {
+  EngineTx,
+  Id,
+  LocalCacheEngine,
+  OrderBy,
+  RelationFetch,
+  Row,
+} from './cache-engine';
+import { stableKey } from './relation-resolver';
+import { surql } from '../../utils/surql';
+import { RecordId } from 'surrealdb';
+
+/**
+ * Default local cache backend: the in-browser SurrealDB-WASM store. Implemented
+ * as a subclass of {@link LocalDatabaseService} so it remains a 100% drop-in for
+ * every existing `this.local.query(...)` / `execute` / `switchStore` / `epoch`
+ * call site (zero behavior change), while adding the engine-neutral verb surface
+ * (`select`/`selectByIds`/`getById`/CRUD) used by the pluggable path.
+ *
+ * Relations are resolved with the SAME shared {@link resolveRelations} as the
+ * SQLite backend, so the two engines decompose `.related()` identically.
+ */
+export class SurrealCacheEngine extends LocalDatabaseService implements LocalCacheEngine {
+  /** SurrealDB needs its SurrealQL schema provisioned locally. */
+  readonly usesSurqlSchema = true;
+
+  /** {@link LocalCacheEngine} alias for {@link LocalDatabaseService.switchStore}. */
+  switchBucket(bucketId: string): Promise<void> {
+    return this.switchStore(bucketId);
+  }
+
+  async fetchRelation(req: RelationFetch): Promise<Row[]> {
+    const { sql, vars } = renderRelationFetchSurql(req);
+    const [rows] = await this.query<[Row[]]>(sql, vars);
+    return rows ?? [];
+  }
+
+  async select(plan: QueryPlan, params: Record<string, unknown> = {}): Promise<Row[]> {
+    // Window materialization: base rows are exactly `plan.ids`, ordered.
+    if (plan.ids) {
+      const result = await this.selectByIds(plan.table, plan.ids, {
+        select: plan.select,
+        orderBy: plan.orderBy,
+      });
+      await resolveRelations(result, plan.relations, this);
+      return result;
+    }
+    const { sql, vars } = renderBaseSelectSurql(plan, params);
+    const [rows] = await this.query<[Row[]]>(sql, vars);
+    const result = rows ?? [];
+    await resolveRelations(result, plan.relations, this);
+    return result;
+  }
+
+  async selectByIds(
+    table: string,
+    ids: Id[],
+    opts?: { select?: string[]; orderBy?: OrderBy }
+  ): Promise<Row[]> {
+    if (ids.length === 0) return [];
+    const projection =
+      opts?.select && opts.select.length > 0 ? ['id', ...opts.select].join(', ') : '*';
+    let sql = `SELECT ${projection} FROM $__ids`;
+    if (opts?.orderBy && opts.orderBy.length > 0) {
+      sql += ` ORDER BY ${opts.orderBy.map(([f, d]) => `${f} ${d}`).join(', ')}`;
+    }
+    const [rows] = await this.query<[Row[]]>(`${sql};`, { __ids: ids });
+    const result = rows ?? [];
+    // Preserve caller's id order when no explicit ORDER BY (SurrealDB does not
+    // guarantee `FROM $ids` order).
+    if (!opts?.orderBy || opts.orderBy.length === 0) {
+      const pos = new Map(ids.map((id, i) => [stableKey(id), i]));
+      result.sort(
+        (a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0)
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Coerce the contract's `Id` (a RecordId, a stable `table:id` string, or a
+   * bare id + the verb's `table` param) to a real RecordId. SurrealDB binds
+   * `$__id` verbatim: a plain string makes `FROM ONLY $__id` "select" the
+   * string itself (a truthy non-row) and `UPSERT $__id` an InternalError, so
+   * string ids silently broke every id-verb on this engine.
+   */
+  private toRecordId(table: string, id: Id): unknown {
+    if (typeof id !== 'string') return id;
+    const raw = id.startsWith(`${table}:`) ? id.slice(table.length + 1) : id;
+    return new RecordId(table, raw);
+  }
+
+  async getById(table: string, id: Id): Promise<Row | null> {
+    const [row] = await this.query<[Row | null]>('SELECT * FROM ONLY $__id;', {
+      __id: this.toRecordId(table, id),
+    });
+    // `FROM ONLY <non-record>` echoes the value back; only a real row counts.
+    return row && typeof row === 'object' ? row : null;
+  }
+
+  async upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void> {
+    const sql = mode === 'merge' ? surql.upsertMerge('__id', '__data') : surql.upsert('__id', '__data');
+    await this.query(surql.seal(sql), { __id: this.toRecordId(table, id), __data: data });
+  }
+
+  async patch(table: string, id: Id, patches: unknown[]): Promise<void> {
+    await this.query(surql.seal('UPDATE ONLY $__id PATCH $__patches'), {
+      __id: this.toRecordId(table, id),
+      __patches: patches,
+    });
+  }
+
+  async delete(table: string, id: Id): Promise<void> {
+    await this.query(surql.seal(surql.delete('__id')), { __id: this.toRecordId(table, id) });
+  }
+
+  /**
+   * Serialized (not strictly atomic) transaction: verbs run in order on the
+   * same serialized query queue. The SurrealDB-WASM store already funnels every
+   * `query()` through one queue, so these never interleave with other work;
+   * true multi-statement atomicity is not required by the current call sites
+   * (single-record CRDT / mutation writes).
+   */
+  async transaction<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T> {
+    const tx: EngineTx = {
+      upsert: (t, id, data, mode) => this.upsert(t, id, data, mode),
+      patch: (t, id, patches) => this.patch(t, id, patches),
+      delete: (t, id) => this.delete(t, id),
+    };
+    return fn(tx);
+  }
+}

package/src/services/logger/index.ts

@@ -1,114 +1,19 @@
-import pino, { Level, type Logger as PinoLogger, type LoggerOptions } from 'pino';
-import { LoggerProvider, BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
-import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-proto';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-import { createContextKey } from '@opentelemetry/api';
-
-const CATEGORY_KEY = createContextKey('Category');
+import pino, { type Level, type Logger as PinoLogger, type LoggerOptions } from 'pino';
+import type { PinoTransmit } from '../../types';
 
 export type Logger = PinoLogger;
 
-// Map pino levels to OTEL severity numbers
-// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#severity-fields
-function mapLevelToSeverityNumber(level: string): number {
-  switch (level) {
-    case 'trace':
-      return 1;
-    case 'debug':
-      return 5;
-    case 'info':
-      return 9;
-    case 'warn':
-      return 13;
-    case 'error':
-      return 17;
-    case 'fatal':
-      return 21;
-    default:
-      return 9;
-  }
-}
-
-export function createLogger(level: Level = 'info', otelEndpoint?: string): Logger {
+export function createLogger(level: Level = 'info', transmit?: PinoTransmit): Logger {
   const browserConfig: LoggerOptions['browser'] = {
     asObject: true,
     write: (o: any) => {
+      // oxlint-disable-next-line no-console
       console.log(JSON.stringify(o));
     },
   };
 
-  if (otelEndpoint) {
-    // Initialize OTEL LoggerProvider
-    const resource = resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: 'spooky-client',
-    });
-
-    const exporter = new OTLPLogExporter({
-      url: otelEndpoint,
-    });
-
-    // Pass processors in constructor as this SDK version requires it
-    const loggerProvider = new LoggerProvider({
-      resource,
-      processors: [new BatchLogRecordProcessor(exporter)],
-    });
-
-    const otelLogger: Record<string, ReturnType<typeof loggerProvider.getLogger>> = {};
-
-    const getOtelLogger = (category: string) => {
-      if (!otelLogger[category]) {
-        otelLogger[category] = loggerProvider.getLogger(category);
-      }
-      return otelLogger[category];
-    };
-
-    browserConfig.transmit = {
-      level: level,
-      send: (levelLabel: string, logEvent: any) => {
-        try {
-          const messages = [...logEvent.messages];
-          const severityNumber = mapLevelToSeverityNumber(levelLabel);
-
-          // Construct the message body
-          let body = '';
-          const msg = messages.pop();
-
-          if (typeof msg === 'string') {
-            body = msg;
-          } else if (msg) {
-            body = JSON.stringify(msg);
-          }
-
-          let category = 'spooky-client::unknown';
-
-          const attributes = {};
-          for (const msg of messages) {
-            if (typeof msg === 'object') {
-              if (msg.Category) {
-                category = msg.Category;
-                delete msg.Category;
-              }
-              Object.assign(attributes, msg);
-            }
-          }
-
-          // Emit to OTEL SDK
-          getOtelLogger(category).emit({
-            severityNumber: severityNumber,
-            severityText: levelLabel.toUpperCase(),
-            body: body,
-            attributes: {
-              ...logEvent.bindings[0],
-              ...attributes,
-            },
-            timestamp: new Date(logEvent.ts),
-          });
-        } catch (e) {
-          console.warn('Failed to transmit log to OTEL endpoint', e);
-        }
-      },
-    };
+  if (transmit) {
+    browserConfig.transmit = transmit;
   }
 
   return pino({

package/src/services/persistence/localstorage.ts

@@ -1,5 +1,5 @@
-import { Logger } from 'pino';
-import { PersistenceClient } from '../../types';
+import type { Logger } from 'pino';
+import type { PersistenceClient } from '../../types';
 
 export class LocalStoragePersistenceClient implements PersistenceClient {
   private logger: Logger;

package/src/services/persistence/resilient.ts

@@ -1,5 +1,5 @@
-import { Logger } from 'pino';
-import { PersistenceClient } from '../../types';
+import type { Logger } from 'pino';
+import type { PersistenceClient } from '../../types';
 
 export class ResilientPersistenceClient implements PersistenceClient {
   private logger: Logger;
@@ -20,10 +20,17 @@ export class ResilientPersistenceClient implements PersistenceClient {
       return await this.inner.get<T>(key);
     } catch (e) {
       this.logger.warn(
-        { key, error: e, Category: 'spooky-client::ResilientPersistenceClient::get' },
+        { key, error: e, Category: 'sp00ky-client::ResilientPersistenceClient::get' },
         'Persistence read failed, dropping key'
       );
-      await this.inner.remove(key).catch(() => {});
+      // Best-effort cleanup of the corrupt key; if removal also fails, the key
+      // just gets dropped again on the next failed read, so the failure is safe.
+      await this.inner.remove(key).catch((removeErr) => {
+        this.logger.debug(
+          { key, error: removeErr, Category: 'sp00ky-client::ResilientPersistenceClient::get' },
+          'Failed to drop corrupt persistence key'
+        );
+      });
       return null;
     }
   }

package/src/services/persistence/surrealdb.ts

@@ -1,13 +1,13 @@
-import { PersistenceClient } from '../../types';
+import type { PersistenceClient } from '../../types';
 import { parseRecordIdString, surql } from '../../utils/index';
-import { Logger } from 'pino';
-import { AbstractDatabaseService } from '../database/database';
+import type { Logger } from 'pino';
+import type { LocalStore } from '../database/cache-engine';
 
 export class SurrealDBPersistenceClient implements PersistenceClient {
   private logger: Logger;
 
   constructor(
-    private db: AbstractDatabaseService,
+    private db: LocalStore,
     logger: Logger
   ) {
     this.logger = logger.child({ service: 'PersistenceClient:SurrealDb' });
@@ -15,11 +15,11 @@ export class SurrealDBPersistenceClient implements PersistenceClient {
 
   async set<T>(key: string, val: T) {
     try {
-      const id = parseRecordIdString(`_spooky_kv:${key}`);
+      const id = parseRecordIdString(`_00_kv:${key}`);
       await this.db.query(surql.seal(surql.upsert('id', 'data')), { id, data: { val } });
     } catch (error) {
       this.logger.error(
-        { error, Category: 'spooky-client::SurrealDBPersistenceClient::set' },
+        { error, Category: 'sp00ky-client::SurrealDBPersistenceClient::set' },
         'Failed to set KV'
       );
       throw error;
@@ -28,7 +28,7 @@ export class SurrealDBPersistenceClient implements PersistenceClient {
 
   async get<T>(key: string) {
     try {
-      const id = parseRecordIdString(`_spooky_kv:${key}`);
+      const id = parseRecordIdString(`_00_kv:${key}`);
       const [result] = await this.db.query<[{ val: T }]>(
         surql.seal(surql.selectById('id', ['val'])),
         {
@@ -41,7 +41,7 @@ export class SurrealDBPersistenceClient implements PersistenceClient {
       return result.val;
     } catch (error) {
       this.logger.warn(
-        { error, Category: 'spooky-client::SurrealDBPersistenceClient::get' },
+        { error, Category: 'sp00ky-client::SurrealDBPersistenceClient::get' },
         'Failed to get KV'
       );
       return null;
@@ -50,11 +50,11 @@ export class SurrealDBPersistenceClient implements PersistenceClient {
 
   async remove(key: string) {
     try {
-      const id = parseRecordIdString(`_spooky_kv:${key}`);
+      const id = parseRecordIdString(`_00_kv:${key}`);
       await this.db.query(surql.seal(surql.delete('id')), { id });
     } catch (err) {
       this.logger.info(
-        { err, Category: 'spooky-client::SurrealDBPersistenceClient::remove' },
+        { err, Category: 'sp00ky-client::SurrealDBPersistenceClient::remove' },
         'Failed to delete KV'
       );
     }