@spooky-sync/core 0.0.0-canary.1

package/src/utils/index.ts

@@ -0,0 +1,172 @@
+import { GetTable, SchemaStructure, TableModel, TableNames } from '@spooky-sync/query-builder';
+import { Uuid, RecordId, Duration } from 'surrealdb';
+import { Logger } from '../services/logger/index';
+import { QueryTimeToLive } from '../types';
+
+export * from './surql';
+export * from './parser';
+export * from './error-classification';
+
+// ==================== RECORDID UTILITIES ====================
+
+export const compareRecordIds = (
+  a: RecordId<string> | string,
+  b: RecordId<string> | string
+): boolean => {
+  const nA = a instanceof RecordId ? encodeRecordId(a) : a;
+  const nB = b instanceof RecordId ? encodeRecordId(b) : b;
+  return nA === nB;
+};
+
+export const encodeRecordId = (recordId: RecordId<string>): string => {
+  return `${recordId.table.toString()}:${recordId.id}`;
+};
+
+export const extractIdPart = (id: string | RecordId<string>): string => {
+  if (typeof id === 'string') {
+    return id.split(':').slice(1).join(':');
+  }
+  // RecordId.id can be string, number, object, or array
+  const idValue = id.id;
+  if (typeof idValue === 'string') {
+    return idValue;
+  }
+  // For other types (number, object, array), convert to string
+  return String(idValue);
+};
+
+export const extractTablePart = (id: string | RecordId<string>): string => {
+  if (typeof id === 'string') {
+    return id.split(':')[0];
+  }
+  return id.table.toString();
+};
+
+export const parseRecordIdString = (id: string): RecordId<string> => {
+  const [table, ...idParts] = id.split(':');
+  return new RecordId(table, idParts.join(':'));
+};
+
+export function generateId(): string {
+  return Uuid.v4().toString().replace(/-/g, '');
+}
+
+export function generateNewTableId<S extends SchemaStructure, T extends TableNames<S>>(
+  tableName: T
+): RecordId {
+  return new RecordId(tableName, generateId());
+}
+
+// ==================== SCHEMA ENCODING/DECODING ====================
+
+export function decodeFromSpooky<S extends SchemaStructure, T extends TableNames<S>>(
+  schema: S,
+  tableName: T,
+  record: TableModel<GetTable<S, T>>
+): TableModel<GetTable<S, T>> {
+  const table = schema.tables.find((t) => t.name === tableName);
+  if (!table) {
+    throw new Error(`Table ${tableName} not found in schema`);
+  }
+
+  const encoded = { ...record } as any;
+
+  for (const field of Object.keys(table.columns)) {
+    const column = table.columns[field] as any;
+    const relation = schema.relationships.find((r) => r.from === tableName && r.field === field);
+    if ((column.recordId || relation) && encoded[field] != null) {
+      if (encoded[field] instanceof RecordId) {
+        encoded[field] = `${encoded[field].table.toString()}:${encoded[field].id}`;
+      } else if (
+        relation &&
+        (encoded[field] instanceof Object || encoded[field] instanceof Array)
+      ) {
+        if (Array.isArray(encoded[field])) {
+          encoded[field] = encoded[field].map((item) =>
+            decodeFromSpooky(schema, relation.to, item)
+          );
+        } else {
+          encoded[field] = decodeFromSpooky(schema, relation.to, encoded[field]);
+        }
+      }
+    }
+  }
+
+  return encoded as TableModel<GetTable<S, T>>;
+}
+
+// ==================== TIME/DURATION UTILITIES ====================
+
+/**
+ * Parse duration string or Duration object to milliseconds
+ */
+export function parseDuration(duration: QueryTimeToLive | Duration): number {
+  if (duration instanceof Duration) {
+    const ms = (duration as any).milliseconds || (duration as any)._milliseconds;
+    if (ms) return Number(ms);
+    const str = duration.toString();
+    if (str !== '[object Object]') return parseDuration(str as any);
+    return 600000;
+  }
+
+  if (typeof duration === 'bigint') {
+    return Number(duration);
+  }
+
+  if (typeof duration !== 'string') return 600000;
+
+  const match = duration.match(/^(\d+)([smh])$/);
+  if (!match) return 600000;
+  const val = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case 's':
+      return val * 1000;
+    case 'h':
+      return val * 3600000;
+    case 'm':
+    default:
+      return val * 60000;
+  }
+}
+
+// ==================== DATABASE UTILITIES ====================
+
+/**
+ * Helper for retrying DB operations with exponential backoff
+ */
+export async function withRetry<T>(
+  logger: Logger,
+  operation: () => Promise<T>,
+  retries = 3,
+  delayMs = 100
+): Promise<T> {
+  let lastError;
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await operation();
+    } catch (err: any) {
+      lastError = err;
+      if (
+        err?.message?.includes('Can not open transaction') ||
+        err?.message?.includes('transaction') ||
+        err?.message?.includes('Database is busy')
+      ) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(
+          {
+            attempt: i + 1,
+            retries,
+            error: msg,
+            Category: 'spooky-client::utils::withRetry',
+          },
+          'Retrying DB operation'
+        );
+        await new Promise((res) => setTimeout(res, delayMs * (i + 1)));
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError;
+}

package/src/utils/parser.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { parseParams, cleanRecord } from './parser';
+
+describe('parseParams', () => {
+  it('passes through plain values unchanged', () => {
+    const schema = {
+      name: { type: 'string' as const, optional: false },
+      age: { type: 'number' as const, optional: false },
+    };
+    const result = parseParams(schema, { name: 'Alice', age: 30 });
+    expect(result).toEqual({ name: 'Alice', age: 30 });
+  });
+
+  it('converts string to RecordId for recordId columns', () => {
+    const schema = {
+      owner: { type: 'string' as const, optional: false, recordId: true },
+    };
+    const result = parseParams(schema, { owner: 'user:123' });
+    expect(result.owner).toBeInstanceOf(RecordId);
+    expect(result.owner.table.toString()).toBe('user');
+    expect(result.owner.id).toBe('123');
+  });
+
+  it('passes through existing RecordId for recordId columns', () => {
+    const schema = {
+      owner: { type: 'string' as const, optional: false, recordId: true },
+    };
+    const rid = new RecordId('user', '456');
+    const result = parseParams(schema, { owner: rid });
+    expect(result.owner).toBe(rid);
+  });
+
+  it('converts string to Date for dateTime columns', () => {
+    const schema = {
+      createdAt: { type: 'string' as const, optional: false, dateTime: true },
+    };
+    const result = parseParams(schema, { createdAt: '2024-01-01T00:00:00Z' });
+    expect(result.createdAt).toBeInstanceOf(Date);
+    expect(result.createdAt.toISOString()).toBe('2024-01-01T00:00:00.000Z');
+  });
+
+  it('converts number (timestamp) to Date for dateTime columns', () => {
+    const schema = {
+      createdAt: { type: 'string' as const, optional: false, dateTime: true },
+    };
+    const ts = 1704067200000; // 2024-01-01T00:00:00.000Z
+    const result = parseParams(schema, { createdAt: ts });
+    expect(result.createdAt).toBeInstanceOf(Date);
+    expect(result.createdAt.getTime()).toBe(ts);
+  });
+
+  it('passes through existing Date for dateTime columns', () => {
+    const schema = {
+      createdAt: { type: 'string' as const, optional: false, dateTime: true },
+    };
+    const date = new Date('2024-01-01');
+    const result = parseParams(schema, { createdAt: date });
+    expect(result.createdAt).toBe(date);
+  });
+
+  it('skips undefined values', () => {
+    const schema = {
+      name: { type: 'string' as const, optional: false },
+      age: { type: 'number' as const, optional: true },
+    };
+    const result = parseParams(schema, { name: 'Alice', age: undefined });
+    expect(result).toEqual({ name: 'Alice' });
+    expect('age' in result).toBe(false);
+  });
+
+  it('throws on invalid recordId value', () => {
+    const schema = {
+      owner: { type: 'string' as const, optional: false, recordId: true },
+    };
+    expect(() => parseParams(schema, { owner: 12345 })).toThrow('Invalid value for owner');
+  });
+
+  it('throws on invalid dateTime value', () => {
+    const schema = {
+      createdAt: { type: 'string' as const, optional: false, dateTime: true },
+    };
+    expect(() => parseParams(schema, { createdAt: true })).toThrow(
+      'Invalid value for createdAt'
+    );
+  });
+});
+
+describe('cleanRecord', () => {
+  const tableSchema = {
+    name: { type: 'string' as const, optional: false },
+    age: { type: 'number' as const, optional: false },
+  };
+
+  it('keeps schema fields and strips non-schema fields', () => {
+    const record = { id: 'user:1', name: 'Alice', age: 30, _internal: true, computed_score: 99 };
+    const result = cleanRecord(tableSchema, record);
+    expect(result).toEqual({ id: 'user:1', name: 'Alice', age: 30 });
+  });
+
+  it('always preserves id even though it is not in schema', () => {
+    const record = { id: 'user:2', extra: 'gone' };
+    const result = cleanRecord(tableSchema, record);
+    expect(result).toEqual({ id: 'user:2' });
+  });
+
+  it('does not coerce or transform values', () => {
+    const date = new Date('2024-01-01');
+    const schema = { created: { type: 'string' as const, optional: false, dateTime: true } };
+    const record = { id: 'x:1', created: date };
+    const result = cleanRecord(schema, record);
+    expect(result.created).toBe(date);
+  });
+
+  it('returns only id when record has no schema fields', () => {
+    const record = { id: 'user:3', unknown1: 'a', unknown2: 'b' };
+    const result = cleanRecord(tableSchema, record);
+    expect(result).toEqual({ id: 'user:3' });
+  });
+
+  it('handles empty record', () => {
+    const result = cleanRecord(tableSchema, {});
+    expect(result).toEqual({});
+  });
+});

package/src/utils/parser.ts

@@ -0,0 +1,46 @@
+import { ColumnSchema, RecordId } from '@spooky-sync/query-builder';
+import { parseRecordIdString } from './index';
+import { DateTime } from 'surrealdb';
+
+export function cleanRecord(
+  tableSchema: Record<string, ColumnSchema>,
+  record: Record<string, any>
+): Record<string, any> {
+  const cleaned: Record<string, any> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === 'id' || key in tableSchema) {
+      cleaned[key] = value;
+    }
+  }
+  return cleaned;
+}
+
+export function parseParams(
+  tableSchema: Record<string, ColumnSchema>,
+  params: Record<string, any>
+) {
+  const parsedParams: Record<string, any> = {};
+  for (const [key, value] of Object.entries(params)) {
+    const column = tableSchema[key];
+    if (column && value !== undefined) {
+      parsedParams[key] = parseValue(key, column, value);
+    }
+  }
+
+  return parsedParams;
+}
+
+function parseValue(name: string, column: ColumnSchema, value: any) {
+  if (column.recordId) {
+    if (value instanceof RecordId) return value;
+    if (typeof value === 'string') return parseRecordIdString(value);
+    throw new Error(`Invalid value for ${name}: ${value}`);
+  }
+  if (column.dateTime) {
+    if (value instanceof Date) return value;
+    if (value instanceof DateTime) return value.toDate();
+    if (typeof value === 'number' || typeof value === 'string') return new Date(value);
+    throw new Error(`Invalid value for ${name}: ${value}`);
+  }
+  return value;
+}

package/src/utils/surql.ts

@@ -0,0 +1,182 @@
+import { MutationEventType } from '../types';
+
+// ==================== TYPES ====================
+
+export interface TxQuery {
+  readonly __brand: 'TxQuery';
+  readonly sql: string;
+  readonly statementCount: number;
+}
+
+export interface SealOptions {
+  /** 0-based index of the inner statement to extract. Default: last statement. */
+  resultIndex?: number;
+}
+
+export interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+
+export interface SurqlHelper {
+  seal(query: string): string;
+  seal<T = void>(query: TxQuery, options?: SealOptions): SealedQuery<T>;
+  tx(queries: string[]): TxQuery;
+  selectById(idVar: string, returnValues: string[]): string;
+  selectByFieldsAnd(
+    table: string,
+    whereVar: ({ field: string; variable: string } | string)[],
+    returnValues: ({ field: string; alias: string } | string)[]
+  ): string;
+  create(idVar: string, dataVar: string): string;
+  createSet(
+    idVar: string,
+    keyDataVars: ({ key: string; variable: string } | { statement: string } | string)[]
+  ): string;
+  upsert(idVar: string, dataVar: string): string;
+  updateMerge(idVar: string, dataVar: string): string;
+  updateSet(
+    idVar: string,
+    keyDataVar: ({ key: string; variable: string } | { statement: string } | string)[]
+  ): string;
+  delete(idVar: string): string;
+  let(name: string, query: string): string;
+  createMutation(
+    t: MutationEventType,
+    mutationIdVar: string,
+    recordIdVar: string,
+    dataVar?: string,
+    beforeRecordVar?: string
+  ): string;
+  returnObject(entries: { key: string; variable: string }[]): string;
+}
+
+// ==================== IMPLEMENTATION ====================
+
+export const surql: SurqlHelper = {
+  seal(query: string | TxQuery, options?: SealOptions): any {
+    if (typeof query === 'string') {
+      return `${query};`;
+    }
+
+    // TxQuery path
+    const txQuery = query;
+    const idx = options?.resultIndex ?? txQuery.statementCount - 1;
+    const sql = `${txQuery.sql};`;
+    return {
+      sql,
+      extract(results: unknown[]): unknown {
+        // +1 to skip the BEGIN null at index 0
+        return results[idx + 1];
+      },
+    } satisfies SealedQuery<unknown>;
+  },
+
+  tx(queries: string[]): TxQuery {
+    return {
+      __brand: 'TxQuery' as const,
+      sql: `BEGIN TRANSACTION;\n${queries.join(';')};\nCOMMIT TRANSACTION`,
+      statementCount: queries.length,
+    };
+  },
+
+  selectById(idVar: string, returnValues: string[]) {
+    return `SELECT ${returnValues.join(',')} FROM ONLY $${idVar}`;
+  },
+
+  selectByFieldsAnd(
+    table: string,
+    whereVar: ({ field: string; variable: string } | string)[],
+    returnValues: ({ field: string; alias: string } | string)[]
+  ) {
+    return `SELECT ${returnValues
+      .map((returnValues) =>
+        typeof returnValues === 'string'
+          ? returnValues
+          : `${returnValues.field} as ${returnValues.alias}`
+      )
+      .join(',')} FROM ${table} WHERE ${whereVar
+      .map((whereVar) =>
+        typeof whereVar === 'string'
+          ? `${whereVar} = $${whereVar}`
+          : `${whereVar.field} = $${whereVar.variable}`
+      )
+      .join(' AND ')}`;
+  },
+
+  create(idVar: string, dataVar: string) {
+    return `CREATE ONLY $${idVar} CONTENT $${dataVar}`;
+  },
+
+  createSet(
+    idVar: string,
+    keyDataVars: ({ key: string; variable: string } | { statement: string } | string)[]
+  ) {
+    return `CREATE ONLY $${idVar} SET ${keyDataVars
+      .map((keyDataVar) =>
+        typeof keyDataVar === 'string'
+          ? `${keyDataVar} = $${keyDataVar}`
+          : 'statement' in keyDataVar
+            ? keyDataVar.statement
+            : `${keyDataVar.key} = $${keyDataVar.variable}`
+      )
+      .join(', ')}`;
+  },
+
+  upsert(idVar: string, dataVar: string) {
+    return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
+  },
+
+  updateMerge(idVar: string, dataVar: string) {
+    return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
+  },
+
+  updateSet(
+    idVar: string,
+    keyDataVar: ({ key: string; variable: string } | { statement: string } | string)[]
+  ) {
+    return `UPDATE $${idVar} SET ${keyDataVar
+      .map((keyDataVar) =>
+        typeof keyDataVar === 'string'
+          ? `${keyDataVar} = $${keyDataVar}`
+          : 'statement' in keyDataVar
+            ? keyDataVar.statement
+            : `${keyDataVar.key} = $${keyDataVar.variable}`
+      )
+      .join(', ')}`;
+  },
+
+  delete(idVar: string) {
+    return `DELETE $${idVar}`;
+  },
+
+  let(name: string, query: string) {
+    return `LET $${name} = (${query})`;
+  },
+
+  createMutation(
+    t: MutationEventType,
+    mutationIdVar: string,
+    recordIdVar: string,
+    dataVar?: string,
+    beforeRecordVar?: string
+  ) {
+    switch (t) {
+      case 'create':
+        return `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+      case 'update': {
+        let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
+        if (beforeRecordVar) {
+          stmt += `, beforeRecord = $${beforeRecordVar}`;
+        }
+        return stmt;
+      }
+      case 'delete':
+        return `CREATE ONLY $${mutationIdVar} SET mutationType = 'delete', recordId = $${recordIdVar}`;
+    }
+  },
+
+  returnObject(entries: { key: string; variable: string }[]) {
+    return `RETURN {${entries.map(({ key, variable }) => `${key}: $${variable}`).join(',')}}`;
+  },
+};

package/src/utils/utils.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import {
+  compareRecordIds,
+  encodeRecordId,
+  extractIdPart,
+  extractTablePart,
+  parseRecordIdString,
+  generateId,
+  parseDuration,
+} from './index';
+
+describe('compareRecordIds', () => {
+  it('returns true for equal strings', () => {
+    expect(compareRecordIds('user:123', 'user:123')).toBe(true);
+  });
+
+  it('returns false for different strings', () => {
+    expect(compareRecordIds('user:123', 'user:456')).toBe(false);
+  });
+
+  it('returns true for equal RecordIds', () => {
+    const a = new RecordId('user', '123');
+    const b = new RecordId('user', '123');
+    expect(compareRecordIds(a, b)).toBe(true);
+  });
+
+  it('returns false for different RecordIds', () => {
+    const a = new RecordId('user', '123');
+    const b = new RecordId('user', '456');
+    expect(compareRecordIds(a, b)).toBe(false);
+  });
+
+  it('returns true for RecordId matching equivalent string', () => {
+    const rid = new RecordId('user', '123');
+    expect(compareRecordIds(rid, 'user:123')).toBe(true);
+  });
+
+  it('returns true for string matching equivalent RecordId', () => {
+    const rid = new RecordId('user', '123');
+    expect(compareRecordIds('user:123', rid)).toBe(true);
+  });
+
+  it('returns false for mismatched RecordId and string', () => {
+    const rid = new RecordId('user', '123');
+    expect(compareRecordIds(rid, 'post:123')).toBe(false);
+  });
+});
+
+describe('encodeRecordId', () => {
+  it('encodes a RecordId to table:id format', () => {
+    const rid = new RecordId('user', 'abc');
+    expect(encodeRecordId(rid)).toBe('user:abc');
+  });
+
+  it('encodes a RecordId with numeric-like id', () => {
+    const rid = new RecordId('post', '42');
+    expect(encodeRecordId(rid)).toBe('post:42');
+  });
+});
+
+describe('extractIdPart', () => {
+  it('extracts id from a string', () => {
+    expect(extractIdPart('user:123')).toBe('123');
+  });
+
+  it('extracts id from a string with colons in the id', () => {
+    expect(extractIdPart('table:some:complex:id')).toBe('some:complex:id');
+  });
+
+  it('extracts string id from a RecordId', () => {
+    const rid = new RecordId('user', 'abc');
+    expect(extractIdPart(rid)).toBe('abc');
+  });
+
+  it('extracts numeric id from a RecordId as string', () => {
+    const rid = new RecordId('user', 42 as any);
+    expect(extractIdPart(rid)).toBe('42');
+  });
+});
+
+describe('extractTablePart', () => {
+  it('extracts table from a string', () => {
+    expect(extractTablePart('user:123')).toBe('user');
+  });
+
+  it('extracts table from a string with colons in the id', () => {
+    expect(extractTablePart('table:some:complex:id')).toBe('table');
+  });
+
+  it('extracts table from a RecordId', () => {
+    const rid = new RecordId('post', 'abc');
+    expect(extractTablePart(rid)).toBe('post');
+  });
+});
+
+describe('parseRecordIdString', () => {
+  it('parses standard table:id format', () => {
+    const rid = parseRecordIdString('user:123');
+    expect(rid).toBeInstanceOf(RecordId);
+    expect(rid.table.toString()).toBe('user');
+    expect(rid.id).toBe('123');
+  });
+
+  it('parses id containing colons', () => {
+    const rid = parseRecordIdString('table:part1:part2');
+    expect(rid.table.toString()).toBe('table');
+    expect(rid.id).toBe('part1:part2');
+  });
+});
+
+describe('generateId', () => {
+  it('returns a 32-character hex string', () => {
+    const id = generateId();
+    expect(id).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('generates unique ids across calls', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateId()));
+    expect(ids.size).toBe(100);
+  });
+});
+
+describe('parseDuration', () => {
+  it('parses seconds', () => {
+    expect(parseDuration('30s')).toBe(30000);
+  });
+
+  it('parses minutes', () => {
+    expect(parseDuration('5m')).toBe(300000);
+  });
+
+  it('parses hours', () => {
+    expect(parseDuration('1h')).toBe(3600000);
+  });
+
+  it('returns default for invalid string', () => {
+    expect(parseDuration('invalid' as any)).toBe(600000);
+  });
+
+  it('returns default for unknown unit', () => {
+    expect(parseDuration('10d' as any)).toBe(600000);
+  });
+
+  it('returns default for non-string non-bigint input', () => {
+    expect(parseDuration(undefined as any)).toBe(600000);
+  });
+
+  it('handles bigint input', () => {
+    expect(parseDuration(5000n as any)).toBe(5000);
+  });
+});