@spooky-sync/core 0.0.0-canary.1

package/src/modules/auth/index.ts

@@ -0,0 +1,267 @@
+import { RemoteDatabaseService } from '../../services/database/remote';
+import { LocalDatabaseService } from '../../services/database/local';
+import { DataModule } from '../data/index';
+import {
+  SchemaStructure,
+  AccessDefinition,
+  ColumnSchema,
+  TypeNameToTypeMap,
+} from '@spooky-sync/query-builder';
+import { Logger } from '../../services/logger/index';
+import { encodeRecordId } from '../../utils/index';
+export * from './events/index';
+import { AuthEventTypes, createAuthEventSystem } from './events/index';
+import { PersistenceClient } from '../../types';
+
+// Helper to pretty print types
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+// Map ColumnSchema (value type string) to actual Typescript type
+type MapColumnType<T extends ColumnSchema> = T['optional'] extends true
+  ? TypeNameToTypeMap[T['type']] | undefined
+  : TypeNameToTypeMap[T['type']];
+
+// Extract params object from SchemaStructure based on access name and method (signIn/signup)
+type ExtractAccessParams<
+  S extends SchemaStructure,
+  Name extends keyof S['access'],
+  Method extends 'signIn' | 'signup',
+> = S['access'] extends undefined
+  ? never
+  : S['access'][Name] extends AccessDefinition
+    ? Prettify<{
+        [K in keyof S['access'][Name][Method]['params']]: MapColumnType<
+          S['access'][Name][Method]['params'][K]
+        >;
+      }>
+    : never;
+
+export class AuthService<S extends SchemaStructure> {
+  // State
+  public token: string | null = null;
+  public currentUser: any | null = null;
+  public isAuthenticated: boolean = false;
+  public isLoading: boolean = true;
+
+  private events = createAuthEventSystem();
+
+  public get eventSystem() {
+    return this.events;
+  }
+
+  constructor(
+    private schema: S,
+    private remote: RemoteDatabaseService,
+    private persistenceClient: PersistenceClient,
+    private logger: Logger
+  ) {}
+
+  async init() {
+    await this.check();
+  }
+
+  getAccessDefinition<Name extends keyof S['access']>(name: Name): AccessDefinition | undefined {
+    return this.schema.access?.[name as string];
+  }
+
+  /**
+   * Subscribe to auth state changes.
+   * callback is called immediately with current value and whenever validation status changes.
+   */
+  subscribe(cb: (userId: string | null) => void): () => void {
+    // Immediate callback
+    cb(this.currentUser?.id || null);
+
+    const id = this.events.subscribe(AuthEventTypes.AuthStateChanged, (event) => {
+      cb(event.payload);
+    });
+
+    return () => {
+      this.events.unsubscribe(id);
+    };
+  }
+
+  private notifyListeners() {
+    const userId = this.currentUser?.id || null;
+    this.events.emit(AuthEventTypes.AuthStateChanged, userId);
+  }
+
+  /**
+   * Check for existing session and validate
+   */
+  async check(accessToken?: string) {
+    this.isLoading = true;
+
+    try {
+      const token = accessToken || (await this.persistenceClient.get<string>('spooky_auth_token'));
+
+      if (!token) {
+        this.logger.debug(
+          { Category: 'spooky-client::AuthService::check' },
+          'No token found in storage or arguments'
+        );
+        this.isLoading = false;
+        this.isAuthenticated = false;
+        this.notifyListeners();
+        return;
+      }
+
+      // Authenticate with the token
+      await this.remote.getClient().authenticate(token);
+
+      // Verify the session by fetching the full user record using $auth.id
+      const result = await this.remote.query('SELECT * FROM ONLY $auth.id');
+
+      const items = Array.isArray(result) && Array.isArray(result[0]) ? result[0] : result;
+      const user = Array.isArray(items) ? items[0] : items;
+
+      if (user && user.id) {
+        this.logger.info(
+          { user, Category: 'spooky-client::AuthService::check' },
+          'Auth check complete (via $auth.id)'
+        );
+        await this.setSession(token, user);
+      } else {
+        this.logger.warn(
+          { Category: 'spooky-client::AuthService::check' },
+          '$auth.id empty, attempting manual user fetch'
+        );
+
+        const manualResult = await this.remote.query(
+          'SELECT * FROM user WHERE id = $auth.id LIMIT 1'
+        );
+        const manualItems =
+          Array.isArray(manualResult) && Array.isArray(manualResult[0])
+            ? manualResult[0]
+            : manualResult;
+        const manualUser = Array.isArray(manualItems) ? manualItems[0] : manualItems;
+
+        if (manualUser && manualUser.id) {
+          this.logger.info(
+            { user: manualUser, Category: 'spooky-client::AuthService::check' },
+            'Auth check complete (via manual fetch)'
+          );
+          await this.setSession(token, manualUser);
+        } else {
+          this.logger.warn(
+            { Category: 'spooky-client::AuthService::check' },
+            'Token valid but user not found via fallback'
+          );
+          await this.signOut();
+        }
+      }
+    } catch (error) {
+      this.logger.error(
+        { error, stack: (error as Error).stack, Category: 'spooky-client::AuthService::check' },
+        'Auth check failed'
+      );
+      await this.signOut();
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  /**
+   * Sign out and clear session
+   */
+  async signOut() {
+    this.token = null;
+    this.currentUser = null;
+    this.isAuthenticated = false;
+
+    await this.persistenceClient.remove('spooky_auth_token');
+
+    try {
+      await this.remote.getClient().invalidate();
+    } catch (e) {
+      // Ignore invalidation errors
+    }
+
+    this.notifyListeners();
+  }
+
+  private async setSession(token: string, user: any) {
+    this.token = token;
+    this.currentUser = user;
+    this.isAuthenticated = true;
+    await this.persistenceClient.set('spooky_auth_token', token);
+    this.notifyListeners();
+  }
+
+  async signUp<Name extends keyof S['access'] & string>(
+    accessName: Name,
+    params: ExtractAccessParams<S, Name, 'signup'>
+  ) {
+    const def = this.getAccessDefinition(accessName);
+    if (!def) throw new Error(`Access definition '${accessName}' not found`);
+
+    // Verify all required params are present
+    // Safe cast params to Record<string, any> for runtime check
+    const runtimeParams = params as Record<string, any>;
+
+    const missingParams = Object.entries(def.signup.params)
+      .filter(([name, schema]) => !schema.optional && !(name in runtimeParams))
+      .map(([name]) => name);
+
+    if (missingParams.length > 0) {
+      throw new Error(
+        `Missing required signup params for '${accessName}': ${missingParams.join(', ')}`
+      );
+    }
+
+    this.logger.info(
+      { accessName, runtimeParams, Category: 'spooky-client::AuthService::signUp' },
+      'Attempting signup'
+    );
+
+    const { access } = await this.remote.getClient().signup({
+      access: accessName,
+      variables: runtimeParams,
+    });
+
+    this.logger.info(
+      { Category: 'spooky-client::AuthService::signUp' },
+      'Signup successful, token received'
+    );
+
+    // After signup, we usually get a token.
+    // We should also fetch the user or trust the token works.
+    // For now, let's just trigger a check() to fully hydrate state
+    await this.check(access);
+  }
+
+  async signIn<Name extends keyof S['access'] & string>(
+    accessName: Name,
+    params: ExtractAccessParams<S, Name, 'signIn'>
+  ) {
+    const def = this.getAccessDefinition(accessName);
+    if (!def) throw new Error(`Access definition '${accessName}' not found`);
+
+    const runtimeParams = params as Record<string, any>;
+
+    // Verify all required params are present
+    const missingParams = Object.entries(def.signIn.params)
+      .filter(([name, schema]) => !schema.optional && !(name in runtimeParams))
+      .map(([name]) => name);
+
+    if (missingParams.length > 0) {
+      throw new Error(
+        `Missing required signin params for '${accessName}': ${missingParams.join(', ')}`
+      );
+    }
+
+    this.logger.info(
+      { accessName, Category: 'spooky-client::AuthService::signIn' },
+      'Attempting signin'
+    );
+
+    const { access } = await this.remote.getClient().signin({
+      access: accessName,
+      variables: runtimeParams,
+    });
+
+    await this.check(access);
+  }
+}

package/src/modules/cache/index.ts

@@ -0,0 +1,241 @@
+import { LocalDatabaseService } from '../../services/database/index';
+import {
+  StreamProcessorService,
+  StreamUpdate,
+  StreamUpdateReceiver,
+} from '../../services/stream-processor/index';
+import { Logger } from '../../services/logger/index';
+import { parseRecordIdString, encodeRecordId, surql } from '../../utils/index';
+import { CacheRecord, QueryConfig } from './types';
+import { RecordVersionArray } from '../../types';
+
+export * from './types';
+
+/**
+ * CacheModule - Centralized storage and DBSP ingestion
+ *
+ * Single responsibility: Handle all local storage operations and DBSP ingestion.
+ * This module acts as the bridge between data operations and persistence.
+ */
+export class CacheModule implements StreamUpdateReceiver {
+  private logger: Logger;
+  private streamUpdateCallback: (update: StreamUpdate) => void;
+  private versionLookups: Record<string, number> = {};
+
+  constructor(
+    private local: LocalDatabaseService,
+    private streamProcessor: StreamProcessorService,
+    streamUpdateCallback: (update: StreamUpdate) => void,
+    logger: Logger
+  ) {
+    this.logger = logger.child({ service: 'CacheModule' });
+    this.streamUpdateCallback = streamUpdateCallback;
+    // Register as receiver for DBSP stream updates
+    this.streamProcessor.addReceiver(this);
+  }
+
+  /**
+   * Implements StreamUpdateReceiver interface
+   * Called directly by StreamProcessor when views change
+   */
+  onStreamUpdate(update: StreamUpdate): void {
+    this.logger.debug(
+      {
+        queryHash: update.queryHash,
+        arrayLength: update.localArray?.length,
+        Category: 'spooky-client::CacheModule::onStreamUpdate',
+      },
+      'Stream update received'
+    );
+    this.streamUpdateCallback(update);
+  }
+
+  public lookup(recordId: string): number {
+    return this.versionLookups[recordId] ?? 0;
+  }
+
+  /**
+   * Save a single record to local DB and ingest into DBSP
+   * Used by mutations (create/update)
+   */
+  async save(cacheRecord: CacheRecord, skipDbInsert: boolean = false): Promise<void> {
+    return this.saveBatch([cacheRecord], skipDbInsert);
+  }
+
+  /**
+   * Save multiple records in a batch
+   * More efficient than calling save() multiple times
+   * Used by sync operations
+   */
+  async saveBatch(records: CacheRecord[], skipDbInsert: boolean = false): Promise<void> {
+    if (records.length === 0) return;
+
+    this.logger.debug(
+      {
+        count: records.length,
+        Category: 'spooky-client::CacheModule::saveBatch',
+      },
+      'Saving record batch'
+    );
+
+    try {
+      const populatedRecords = records.map((record) => {
+        if (!record.version) throw new Error('Record version is required');
+        return {
+          ...record,
+          record: {
+            ...record.record,
+            spooky_rv: record.version,
+          },
+        };
+      });
+
+      if (!skipDbInsert) {
+        const query = surql.seal<void>(
+          surql.tx(
+            populatedRecords.map((_, i) => {
+              return surql.upsert(`id${i}`, `content${i}`);
+            })
+          )
+        );
+
+        const params = populatedRecords.reduce(
+          (acc, record, i) => {
+            const { id, ...content } = record.record;
+            return {
+              ...acc,
+              [`id${i}`]: id,
+              [`content${i}`]: content,
+            };
+          },
+          {} as Record<string, any>
+        );
+
+        await this.local.execute(query, params);
+      }
+
+      // 2. Batch ingest into DBSP (use populatedRecords which has spooky_rv set)
+      for (const record of populatedRecords) {
+        const recordId = encodeRecordId(record.record.id);
+        this.versionLookups[recordId] = record.version;
+        this.streamProcessor.ingest(record.table, record.op, recordId, record.record);
+      }
+
+      this.logger.debug(
+        { count: records.length, Category: 'spooky-client::CacheModule::saveBatch' },
+        'Batch saved successfully'
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, count: records.length, Category: 'spooky-client::CacheModule::saveBatch' },
+        'Failed to save batch'
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Delete a record from local DB and ingest deletion into DBSP
+   */
+  async delete(table: string, id: string, skipDbDelete: boolean = false): Promise<void> {
+    this.logger.debug(
+      { table, id, Category: 'spooky-client::CacheModule::delete' },
+      'Deleting record'
+    );
+
+    try {
+      // 1. Delete from local database
+      if (!skipDbDelete) {
+        await this.local.query('DELETE $id', { id: parseRecordIdString(id) });
+      }
+
+      // 2. Ingest deletion into DBSP
+      delete this.versionLookups[id];
+      await this.streamProcessor.ingest(table, 'DELETE', id, {});
+
+      this.logger.debug(
+        { table, id, Category: 'spooky-client::CacheModule::delete' },
+        'Record deleted successfully'
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, table, id, Category: 'spooky-client::CacheModule::delete' },
+        'Failed to delete record'
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Register a query with DBSP to create a materialized view
+   * Returns the initial result array
+   */
+  registerQuery(config: QueryConfig): { localArray: RecordVersionArray } {
+    this.logger.debug(
+      {
+        queryHash: config.queryHash,
+        surql: config.surql,
+        Category: 'spooky-client::CacheModule::registerQuery',
+      },
+      'Registering query'
+    );
+
+    try {
+      const update = this.streamProcessor.registerQueryPlan({
+        queryHash: config.queryHash,
+        surql: config.surql,
+        params: config.params,
+        ttl: config.ttl,
+        lastActiveAt: config.lastActiveAt,
+        localArray: [],
+        remoteArray: [],
+        meta: {
+          tableName: '',
+        },
+      });
+
+      if (!update) {
+        throw new Error('Failed to register query with DBSP');
+      }
+
+      this.logger.debug(
+        {
+          queryHash: config.queryHash,
+          arrayLength: update.localArray?.length,
+          Category: 'spooky-client::CacheModule::registerQuery',
+        },
+        'Query registered successfully'
+      );
+
+      return { localArray: update.localArray };
+    } catch (err) {
+      this.logger.error(
+        { err, queryHash: config.queryHash, Category: 'spooky-client::CacheModule::registerQuery' },
+        'Failed to register query'
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Unregister a query from DBSP
+   */
+  unregisterQuery(queryHash: string): void {
+    this.logger.debug(
+      { queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+      'Unregistering query'
+    );
+    try {
+      this.streamProcessor.unregisterQueryPlan(queryHash);
+      this.logger.debug(
+        { queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+        'Query unregistered successfully'
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, queryHash, Category: 'spooky-client::CacheModule::unregisterQuery' },
+        'Failed to unregister query'
+      );
+    }
+  }
+}

package/src/modules/cache/types.ts

@@ -0,0 +1,19 @@
+import { RecordId, Duration } from 'surrealdb';
+import { QueryTimeToLive, RecordVersionArray } from '../../types';
+
+export type RecordWithId = Record<string, any> & { id: RecordId<string> };
+
+export interface QueryConfig {
+  queryHash: string;
+  surql: string;
+  params: Record<string, any>;
+  ttl: QueryTimeToLive | Duration;
+  lastActiveAt: Date;
+}
+
+export interface CacheRecord {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  record: RecordWithId;
+  version: number;
+}

package/src/modules/data/data.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { parseUpdateOptions } from './index';
+
+describe('parseUpdateOptions', () => {
+  it('returns empty options when no debounce', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' });
+    expect(result).toEqual({});
+  });
+
+  it('returns empty options when options is undefined', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' }, undefined);
+    expect(result).toEqual({});
+  });
+
+  it('returns empty options when debounced is false', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' }, { debounced: false });
+    expect(result).toEqual({});
+  });
+
+  it('debounced: true uses default delay (200) and key = id', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' }, { debounced: true });
+    expect(result).toEqual({
+      debounced: {
+        delay: 200,
+        key: 'user:1',
+      },
+    });
+  });
+
+  it('supports custom delay', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' }, {
+      debounced: { delay: 500 },
+    });
+    expect(result.debounced?.delay).toBe(500);
+  });
+
+  it('supports custom key type recordId', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice', age: 30 }, {
+      debounced: { key: 'recordId' },
+    });
+    expect(result.debounced?.key).toBe('user:1');
+  });
+
+  it('key: recordId_x_fields generates composite key from id + sorted field names', () => {
+    const result = parseUpdateOptions(
+      'user:1',
+      { name: 'Alice', age: 30, email: 'a@b.com' },
+      { debounced: { key: 'recordId_x_fields' } }
+    );
+    expect(result.debounced?.key).toBe('user:1::age#email#name');
+  });
+
+  it('uses defaults when debounced is object with no key or delay', () => {
+    const result = parseUpdateOptions('user:1', { name: 'Alice' }, { debounced: {} });
+    expect(result.debounced?.delay).toBe(200);
+    expect(result.debounced?.key).toBe('user:1');
+  });
+});