@pattern-stack/codegen 0.4.1 → 0.4.3

package/runtime/subsystems/storage/storage.memory-backend.ts

@@ -0,0 +1,78 @@
+/**
+ * Storage subsystem — in-memory backend
+ *
+ * Stores files as Buffers in a Map. Intended for unit tests only.
+ * All state is lost when the process exits.
+ *
+ * - getUrl returns `memory://{key}` (not a real URL, useful for assertions)
+ * - All methods throw on failure (missing keys, etc.)
+ */
+import type { IStorageService } from './storage.protocol';
+import { toBuffer } from './storage.utils';
+
+interface MemoryEntry {
+  data: Buffer;
+  contentType?: string;
+}
+
+export class MemoryStorageBackend implements IStorageService {
+  private readonly store = new Map<string, MemoryEntry>();
+
+  async upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<string> {
+    const buffer = await toBuffer(data);
+    this.store.set(key, { data: buffer, contentType });
+    return key;
+  }
+
+  async download(key: string): Promise<Buffer> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    return entry.data;
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!this.store.has(key)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    this.store.delete(key);
+  }
+
+  async getUrl(key: string, _expiresInSeconds?: number): Promise<string> {
+    if (!this.store.has(key)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    return `memory://${key}`;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const keys = Array.from(this.store.keys());
+    if (prefix === undefined) return keys;
+    return keys.filter((k) => k.startsWith(prefix));
+  }
+
+  async downloadStream(key: string): Promise<ReadableStream> {
+    const buffer = await this.download(key);
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array(buffer));
+        controller.close();
+      },
+    });
+  }
+
+  /** Clear all stored files. Useful for test teardown. */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Return number of stored files. Useful for test assertions. */
+  size(): number {
+    return this.store.size;
+  }
+}

package/runtime/subsystems/storage/storage.module.ts

@@ -0,0 +1,60 @@
+/**
+ * Storage subsystem — NestJS module factory
+ *
+ * Register once in AppModule (global: true means all other modules can inject
+ * STORAGE without importing StorageModule themselves):
+ *
+ * ```typescript
+ * // app.module.ts
+ * @Module({
+ *   imports: [
+ *     StorageModule.forRoot({ backend: 'local', basePath: './uploads' }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Swap to memory backend in tests:
+ * ```typescript
+ * Test.createTestingModule({
+ *   imports: [StorageModule.forRoot({ backend: 'memory' })],
+ * });
+ * ```
+ */
+import { type DynamicModule, Module } from '@nestjs/common';
+import { LocalStorageBackend } from './storage.local-backend';
+import { MemoryStorageBackend } from './storage.memory-backend';
+import { STORAGE } from './storage.tokens';
+
+export interface StorageModuleOptions {
+  /** Which backend to activate. */
+  backend: 'local' | 'memory';
+  /**
+   * Base path for the local backend (resolved to an absolute path).
+   * Ignored when backend is 'memory'. Defaults to `./storage`.
+   */
+  basePath?: string;
+}
+
+@Module({})
+export class StorageModule {
+  static forRoot(options: StorageModuleOptions = { backend: 'local' }): DynamicModule {
+    const provider =
+      options.backend === 'local'
+        ? {
+            provide: STORAGE,
+            useFactory: () => new LocalStorageBackend(options.basePath ?? './storage'),
+          }
+        : {
+            provide: STORAGE,
+            useClass: MemoryStorageBackend,
+          };
+
+    return {
+      module: StorageModule,
+      global: true,
+      providers: [provider],
+      exports: [STORAGE],
+    };
+  }
+}

package/runtime/subsystems/storage/storage.protocol.ts

@@ -0,0 +1,78 @@
+/**
+ * Storage subsystem — protocol (port)
+ *
+ * IStorageService is the hexagonal port. Use cases inject this interface via
+ * STORAGE token. They never depend on a specific backend implementation.
+ *
+ * All methods throw on failure — callers must handle upload/download errors
+ * explicitly. There is no null-return behavior like CacheService.
+ *
+ * Users who need cloud storage (S3, GCS, R2) implement this interface
+ * directly. No Drizzle backend exists — files in Postgres is an antipattern.
+ */
+
+// ============================================================================
+// IStorageService
+// ============================================================================
+
+export interface IStorageService {
+  /**
+   * Upload a file and return the stored key (same as the input key).
+   *
+   * @param key - Storage key / path (e.g. 'avatars/user-123.png')
+   * @param data - File contents as a Buffer or a ReadableStream
+   * @param contentType - Optional MIME type (e.g. 'image/png')
+   * @returns The stored key
+   * @throws On any write failure
+   */
+  upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<string>;
+
+  /**
+   * Download a file by key and return its contents as a Buffer.
+   *
+   * @throws If the file does not exist or cannot be read
+   */
+  download(key: string): Promise<Buffer>;
+
+  /**
+   * Delete a file by key.
+   *
+   * @throws If the file does not exist or cannot be deleted
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Return a URL for accessing the file.
+   *
+   * For local backend: returns a `file://` URI.
+   * For cloud backends: returns a presigned URL that expires after `expiresInSeconds`.
+   *
+   * @param key - Storage key
+   * @param expiresInSeconds - URL expiry (ignored by local/memory backends)
+   * @throws If the file does not exist
+   */
+  getUrl(key: string, expiresInSeconds?: number): Promise<string>;
+
+  /**
+   * Check whether a file exists at the given key.
+   *
+   * @returns `true` if the file exists, `false` otherwise
+   * @throws Only on unexpected I/O errors (not on simple absence)
+   */
+  exists(key: string): Promise<boolean>;
+
+  /**
+   * List all stored keys, optionally filtered by prefix.
+   *
+   * @param prefix - Optional prefix filter (e.g. 'avatars/')
+   * @returns Array of keys matching the prefix (or all keys if omitted)
+   */
+  list(prefix?: string): Promise<string[]>;
+
+  /**
+   * Download a file by key and return its contents as a Web ReadableStream.
+   *
+   * @throws If the file does not exist or cannot be read
+   */
+  downloadStream(key: string): Promise<ReadableStream>;
+}

package/runtime/subsystems/storage/storage.tokens.ts

@@ -0,0 +1,9 @@
+/**
+ * Injection token for the storage service.
+ *
+ * Usage in use cases:
+ * ```typescript
+ * constructor(@Inject(STORAGE) private readonly storage: IStorageService) {}
+ * ```
+ */
+export const STORAGE = Symbol('STORAGE');

package/runtime/subsystems/storage/storage.utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Storage subsystem — shared utilities
+ */
+
+/**
+ * Convert a Buffer or Web ReadableStream to a Node.js Buffer.
+ */
+export async function toBuffer(data: Buffer | ReadableStream): Promise<Buffer> {
+  if (Buffer.isBuffer(data)) {
+    return data;
+  }
+  const reader = (data as ReadableStream<Uint8Array>).getReader();
+  const chunks: Uint8Array[] = [];
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}

package/runtime/subsystems/sync/deep-equal.differ.ts

@@ -0,0 +1,198 @@
+/**
+ * DeepEqualDiffer — default `IFieldDiffer<T>` for the sync subsystem (SYNC-5).
+ *
+ * Walks every field of `incoming` against `existing`, emitting a structured
+ * per-field diff (`{ from, to }`) for every field whose value changed.
+ * Returns `'noop'` when the record is unchanged.
+ *
+ * Design decisions (extracted from dealbrain-v2 + HS-9 findings):
+ *
+ * 1. **Ignore list** — row metadata that sinks/services stamp unconditionally
+ *    so upstream cannot reasonably disagree:
+ *      `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`,
+ *      `lastModifiedAt`, `fields`, `providerMetadata`
+ *    (`fields` is the EAV bag — it's diffed by the sink's EAV dual-write
+ *    path, not at the canonical-record layer.)
+ *
+ * 2. **`providerChangedFields` hint (CDC)** — when present, restricts the
+ *    comparison to the hinted field set. The hint is advisory; fields in
+ *    the ignore list are still filtered out even when hinted. Provider
+ *    hints are field-NAME-level; they don't override the ignore rules.
+ *
+ * 3. **Date → ISO string** — `Date` instances are normalized to
+ *    `toISOString()` before comparison. Sinks return `Date` from the DB
+ *    driver; adapters typically deliver strings. Direct `===` would
+ *    always say "changed."
+ *
+ * 4. **Decimal-string vs number** — Postgres `numeric` columns return as
+ *    strings through Drizzle; adapters deliver numbers. When one side is a
+ *    number and the other is a numeric string that parses to the same
+ *    number, they're equal. The normalizer does NOT coerce non-numeric
+ *    strings, and it preserves zero-vs-null distinction.
+ *
+ * 5. **null-existing path** — `diff(null, incoming)` produces a full
+ *    created-shape diff (`{from: null, to: <value>}` for every non-ignored
+ *    field). Orchestrator sees this and records `operation: 'created'`.
+ */
+import { Injectable } from '@nestjs/common';
+import type {
+  DiffResult,
+  FieldDiff,
+  IFieldDiffer,
+} from './sync-field-diff.protocol';
+
+/**
+ * Default ignore list. Keep in sync with consumer canonical-record shapes —
+ * adding a row-metadata field here means no sync will ever mark it changed.
+ */
+const DEFAULT_IGNORE_FIELDS: ReadonlySet<string> = new Set([
+  'id',
+  'createdAt',
+  'updatedAt',
+  'deletedAt',
+  'type',
+  'lastModifiedAt',
+  'fields',
+  'providerMetadata',
+]);
+
+export interface DeepEqualDifferOptions {
+  /**
+   * Extra field names to ignore in addition to the defaults. Consumers can
+   * pass `['sync_version']` etc. to augment the base list; values here are
+   * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.
+   */
+  readonly ignore?: readonly string[];
+}
+
+@Injectable()
+export class DeepEqualDiffer<T extends Record<string, unknown>>
+  implements IFieldDiffer<T>
+{
+  private readonly ignore: ReadonlySet<string>;
+
+  constructor(opts: DeepEqualDifferOptions = {}) {
+    if (opts.ignore && opts.ignore.length > 0) {
+      this.ignore = new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);
+    } else {
+      this.ignore = DEFAULT_IGNORE_FIELDS;
+    }
+  }
+
+  diff(
+    existing: T | null,
+    incoming: T,
+    providerChangedFields?: string[],
+  ): DiffResult {
+    // Created-shape: every non-ignored field becomes `{from: null, to}`.
+    if (existing === null) {
+      const out: FieldDiff = {};
+      for (const key of Object.keys(incoming)) {
+        if (this.ignore.has(key)) continue;
+        const value = (incoming as Record<string, unknown>)[key];
+        // Skip fields that are themselves null/undefined — a created record
+        // doesn't need to declare "this field is null now" for every
+        // untouched column.
+        if (value === null || value === undefined) continue;
+        out[key] = { from: null, to: value };
+      }
+      return Object.keys(out).length === 0 ? 'noop' : out;
+    }
+
+    // Field set to compare. `providerChangedFields` narrows to a hint set;
+    // ignored fields are filtered out regardless of hint.
+    const candidates = new Set<string>();
+    if (providerChangedFields && providerChangedFields.length > 0) {
+      for (const key of providerChangedFields) {
+        if (!this.ignore.has(key)) candidates.add(key);
+      }
+    } else {
+      for (const key of Object.keys(incoming)) {
+        if (!this.ignore.has(key)) candidates.add(key);
+      }
+      // Also include keys that exist on existing but not on incoming —
+      // e.g. a field that was cleared. This would otherwise be missed when
+      // incoming carries an undefined column we drop from the iteration.
+      for (const key of Object.keys(existing)) {
+        if (this.ignore.has(key)) continue;
+        if (!(key in (incoming as Record<string, unknown>))) continue;
+        candidates.add(key);
+      }
+    }
+
+    const out: FieldDiff = {};
+    for (const key of candidates) {
+      const before = (existing as Record<string, unknown>)[key];
+      const after = (incoming as Record<string, unknown>)[key];
+      if (!isEqual(before, after)) {
+        out[key] = { from: before ?? null, to: after ?? null };
+      }
+    }
+
+    return Object.keys(out).length === 0 ? 'noop' : out;
+  }
+}
+
+// ─── equality helpers ───────────────────────────────────────────────────────
+
+/**
+ * Field-level equality with the canonical-sync normalizations:
+ *   - Date → toISOString (adapters deliver strings)
+ *   - numeric-string vs number → numeric equality when both parse
+ *   - deep equality for plain objects/arrays (single-level is enough for
+ *     canonical records; nested records travel as jsonb columns where the
+ *     sink already owns the comparison)
+ */
+function isEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+
+  const na = normalize(a);
+  const nb = normalize(b);
+  if (na === nb) return true;
+
+  // After normalization: both may still be non-primitive objects.
+  if (
+    typeof na === 'object' &&
+    typeof nb === 'object' &&
+    na !== null &&
+    nb !== null
+  ) {
+    return deepEqualObject(na as Record<string, unknown>, nb as Record<string, unknown>);
+  }
+
+  // Numeric string ↔ number: when one side is a number and the other is a
+  // string that parses to the same finite number.
+  const numericEqual = maybeNumericEqual(na, nb) || maybeNumericEqual(nb, na);
+  return numericEqual;
+}
+
+function normalize(value: unknown): unknown {
+  if (value instanceof Date) return value.toISOString();
+  return value;
+}
+
+function maybeNumericEqual(a: unknown, b: unknown): boolean {
+  // a is string-shape, b is number — parse a and compare. Only when the
+  // string looks numeric AND the parse round-trips (no silent NaN pass-
+  // through on non-numeric strings).
+  if (typeof a !== 'string' || typeof b !== 'number') return false;
+  if (a.trim() === '') return false;
+  const parsed = Number(a);
+  if (!Number.isFinite(parsed)) return false;
+  return parsed === b;
+}
+
+function deepEqualObject(
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+): boolean {
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in b)) return false;
+    if (!isEqual(a[key], b[key])) return false;
+  }
+  return true;
+}