reqon-dsl 0.2.0

package/src/stores/file.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FileStore } from './file.js';
+
+describe('FileStore', () => {
+  const TEST_DIR = '.reqon-test-stores';
+
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  it('should create directory and file on first write', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+
+    expect(existsSync(join(TEST_DIR, 'test-store.json'))).toBe(true);
+  });
+
+  it('should create .gitignore in data directory', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+    // Trigger initialization by calling any store method
+    await store.get('nonexistent');
+
+    const gitignorePath = join(TEST_DIR, '.gitignore');
+    expect(existsSync(gitignorePath)).toBe(true);
+    const content = readFileSync(gitignorePath, 'utf-8');
+    expect(content).toContain('*.json');
+  });
+
+  it('should get a record by key', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+    const record = await store.get('1');
+
+    expect(record).toEqual({ id: '1', name: 'Alice' });
+  });
+
+  it('should return null for non-existent key', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    const record = await store.get('nonexistent');
+    expect(record).toBeNull();
+  });
+
+  it('should update existing record', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice', age: 30 });
+    await store.update('1', { age: 31 });
+
+    const record = await store.get('1');
+    expect(record).toEqual({ id: '1', name: 'Alice', age: 31 });
+  });
+
+  it('should create record on update if not exists', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.update('1', { name: 'Alice' });
+
+    const record = await store.get('1');
+    expect(record).toEqual({ name: 'Alice' });
+  });
+
+  it('should delete a record', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+    await store.delete('1');
+
+    const record = await store.get('1');
+    expect(record).toBeNull();
+  });
+
+  it('should list all records', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+    await store.set('2', { id: '2', name: 'Bob' });
+
+    const records = await store.list();
+    expect(records).toHaveLength(2);
+  });
+
+  it('should filter records with where clause', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice', active: true });
+    await store.set('2', { id: '2', name: 'Bob', active: false });
+    await store.set('3', { id: '3', name: 'Charlie', active: true });
+
+    const records = await store.list({ where: { active: true } });
+    expect(records).toHaveLength(2);
+    expect(records.map(r => r.name)).toContain('Alice');
+    expect(records.map(r => r.name)).toContain('Charlie');
+  });
+
+  it('should support limit and offset', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+    await store.set('2', { id: '2', name: 'Bob' });
+    await store.set('3', { id: '3', name: 'Charlie' });
+
+    const records = await store.list({ offset: 1, limit: 1 });
+    expect(records).toHaveLength(1);
+  });
+
+  it('should clear all records', async () => {
+    const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+    await store.set('1', { id: '1', name: 'Alice' });
+    await store.set('2', { id: '2', name: 'Bob' });
+    await store.clear();
+
+    const records = await store.list();
+    expect(records).toHaveLength(0);
+  });
+
+  describe('batch mode', () => {
+    it('should not write to disk until flush in batch mode', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR, persist: 'batch' });
+      const filePath = store.getFilePath();
+
+      await store.set('1', { id: '1', name: 'Alice' });
+
+      // File exists but should be empty or not contain data yet
+      const contentBefore = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '{}';
+      const parsedBefore = JSON.parse(contentBefore);
+      expect(Object.keys(parsedBefore)).toHaveLength(0);
+
+      // After flush, data should be persisted
+      store.flush();
+
+      const contentAfter = readFileSync(filePath, 'utf-8');
+      const parsedAfter = JSON.parse(contentAfter);
+      expect(parsedAfter['1']).toEqual({ id: '1', name: 'Alice' });
+    });
+  });
+
+  describe('persistence', () => {
+    it('should persist data across store instances', async () => {
+      const store1 = new FileStore('test-store', { baseDir: TEST_DIR });
+      await store1.set('1', { id: '1', name: 'Alice' });
+
+      const store2 = new FileStore('test-store', { baseDir: TEST_DIR });
+      const record = await store2.get('1');
+
+      expect(record).toEqual({ id: '1', name: 'Alice' });
+    });
+
+    it('should reload data from disk', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+      await store.set('1', { id: '1', name: 'Alice' });
+
+      // Manually modify the file
+      const filePath = store.getFilePath();
+      const content = JSON.parse(readFileSync(filePath, 'utf-8'));
+      content['1'].name = 'Modified';
+      require('fs').writeFileSync(filePath, JSON.stringify(content));
+
+      // Reload and check
+      await store.reload();
+      const record = await store.get('1');
+      expect(record?.name).toBe('Modified');
+    });
+  });
+
+  describe('pretty printing', () => {
+    it('should pretty-print JSON by default', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+      await store.set('1', { id: '1', name: 'Alice' });
+
+      const content = readFileSync(store.getFilePath(), 'utf-8');
+      expect(content).toContain('\n'); // Pretty printed has newlines
+    });
+
+    it('should compact JSON when pretty is false', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR, pretty: false });
+      await store.set('1', { id: '1', name: 'Alice' });
+
+      const content = readFileSync(store.getFilePath(), 'utf-8');
+      expect(content).not.toContain('\n'); // Compact has no newlines
+    });
+  });
+
+  describe('count', () => {
+    it('should return total count when no filter', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      await store.set('1', { id: '1', name: 'Alice', status: 'active' });
+      await store.set('2', { id: '2', name: 'Bob', status: 'inactive' });
+      await store.set('3', { id: '3', name: 'Charlie', status: 'active' });
+
+      const count = await store.count();
+      expect(count).toBe(3);
+    });
+
+    it('should return count matching where clause', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      await store.set('1', { id: '1', name: 'Alice', status: 'active' });
+      await store.set('2', { id: '2', name: 'Bob', status: 'inactive' });
+      await store.set('3', { id: '3', name: 'Charlie', status: 'active' });
+
+      const count = await store.count({ where: { status: 'active' } });
+      expect(count).toBe(2);
+    });
+
+    it('should return 0 when no records match', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      await store.set('1', { id: '1', status: 'active' });
+
+      const count = await store.count({ where: { status: 'unknown' } });
+      expect(count).toBe(0);
+    });
+
+    it('should ignore limit and offset for counting', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      await store.set('1', { id: '1', status: 'active' });
+      await store.set('2', { id: '2', status: 'active' });
+      await store.set('3', { id: '3', status: 'active' });
+
+      // limit/offset should not affect count - count returns total matching records
+      const count = await store.count({ where: { status: 'active' }, limit: 1, offset: 1 });
+      expect(count).toBe(3);
+    });
+
+    it('should return 0 for empty store', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      const count = await store.count();
+      expect(count).toBe(0);
+    });
+  });
+
+  describe('utilities', () => {
+    it('should report size correctly', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      expect(store.size()).toBe(0);
+
+      await store.set('1', { id: '1' });
+      await store.set('2', { id: '2' });
+
+      expect(store.size()).toBe(2);
+    });
+
+    it('should dump all records', async () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+
+      await store.set('1', { id: '1', name: 'Alice' });
+      await store.set('2', { id: '2', name: 'Bob' });
+
+      const dump = store.dump();
+      expect(dump).toHaveLength(2);
+    });
+
+    it('should return file path', () => {
+      const store = new FileStore('test-store', { baseDir: TEST_DIR });
+      expect(store.getFilePath()).toBe(join(TEST_DIR, 'test-store.json'));
+    });
+  });
+});

package/src/stores/file.ts

@@ -0,0 +1,211 @@
+import { writeFile } from 'node:fs/promises';
+import { writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import type { StoreAdapter, StoreFilter } from './types.js';
+import { applyStoreFilter } from './types.js';
+import {
+  ensureDirectory,
+  readJsonFile,
+  serialize,
+} from '../utils/file.js';
+
+export interface FileStoreOptions {
+  /** Base directory for data files (default: '.reqon-data') */
+  baseDir?: string;
+  /** Write mode: 'immediate' writes on every change, 'batch' only on flush/close, 'debounce' batches writes */
+  persist?: 'immediate' | 'batch' | 'debounce';
+  /** Pretty-print JSON for readability (default: true) */
+  pretty?: boolean;
+  /** Debounce delay in milliseconds (default: 100ms, only used with persist: 'debounce') */
+  debounceMs?: number;
+}
+
+const DEFAULT_OPTIONS: Required<FileStoreOptions> = {
+  baseDir: '.reqon-data',
+  persist: 'immediate',
+  pretty: true,
+  debounceMs: 100,
+};
+
+/**
+ * File-based JSON store for local development
+ * Persists data to .reqon-data/{name}.json
+ */
+export class FileStore implements StoreAdapter {
+  private data: Map<string, Record<string, unknown>> = new Map();
+  private filePath: string;
+  private options: Required<FileStoreOptions>;
+  private dirty = false;
+  private initialized: Promise<void>;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private pendingWrite: Promise<void> | null = null;
+
+  constructor(name: string, options: FileStoreOptions = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.filePath = join(this.options.baseDir, `${name}.json`);
+    this.initialized = this.init();
+  }
+
+  private async init(): Promise<void> {
+    const dir = dirname(this.filePath);
+    await ensureDirectory(dir);
+    // Create .gitignore if it doesn't exist
+    const gitignorePath = join(dir, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+      await writeFile(gitignorePath, '# Reqon local data\n*.json\n', 'utf-8');
+    }
+    await this.load();
+  }
+
+  private async load(): Promise<void> {
+    const parsed = await readJsonFile<Record<string, Record<string, unknown>>>(this.filePath);
+    if (parsed) {
+      this.data = new Map(Object.entries(parsed));
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (this.options.persist === 'batch') {
+      this.dirty = true;
+      return;
+    }
+    if (this.options.persist === 'debounce') {
+      this.dirty = true;
+      this.scheduleDebouncedWrite();
+      return;
+    }
+    await this.writeToDisk();
+  }
+
+  private scheduleDebouncedWrite(): void {
+    // Clear existing timer if any
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    // Schedule new write
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      if (this.dirty && !this.pendingWrite) {
+        this.pendingWrite = this.writeToDisk().finally(() => {
+          this.pendingWrite = null;
+        });
+      }
+    }, this.options.debounceMs);
+  }
+
+  private async writeToDisk(): Promise<void> {
+    const obj = Object.fromEntries(this.data);
+    const content = serialize(obj, this.options.pretty);
+    await writeFile(this.filePath, content, 'utf-8');
+    this.dirty = false;
+  }
+
+  /** Synchronous write for flush/close operations */
+  private writeToDiskSync(): void {
+    const obj = Object.fromEntries(this.data);
+    const content = serialize(obj, this.options.pretty);
+    writeFileSync(this.filePath, content, 'utf-8');
+    this.dirty = false;
+  }
+
+  async get(key: string): Promise<Record<string, unknown> | null> {
+    await this.initialized;
+    return this.data.get(key) ?? null;
+  }
+
+  async set(key: string, value: Record<string, unknown>): Promise<void> {
+    await this.initialized;
+    this.data.set(key, { ...value });
+    await this.persist();
+  }
+
+  async bulkSet(records: Array<{ key: string; value: Record<string, unknown> }>): Promise<void> {
+    await this.initialized;
+    // Set all records in memory first (no disk I/O per record)
+    for (const { key, value } of records) {
+      this.data.set(key, { ...value });
+    }
+    // Single persist operation for all records
+    await this.persist();
+  }
+
+  async update(key: string, value: Partial<Record<string, unknown>>): Promise<void> {
+    await this.initialized;
+    const existing = this.data.get(key);
+    if (existing) {
+      this.data.set(key, { ...existing, ...value });
+    } else {
+      this.data.set(key, value as Record<string, unknown>);
+    }
+    await this.persist();
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.initialized;
+    this.data.delete(key);
+    await this.persist();
+  }
+
+  async list(filter?: StoreFilter): Promise<Record<string, unknown>[]> {
+    await this.initialized;
+    return applyStoreFilter(Array.from(this.data.values()), filter);
+  }
+
+  async count(filter?: StoreFilter): Promise<number> {
+    await this.initialized;
+    // Apply only the where clause for counting (ignore limit/offset)
+    const filtered = applyStoreFilter(Array.from(this.data.values()), {
+      where: filter?.where,
+    });
+    return filtered.length;
+  }
+
+  async clear(): Promise<void> {
+    await this.initialized;
+    this.data.clear();
+    await this.persist();
+  }
+
+  /**
+   * Flush pending changes to disk (needed in 'batch' or 'debounce' mode)
+   * Uses synchronous I/O to ensure data is written before process exits
+   */
+  flush(): void {
+    // Cancel any pending debounce timer
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.dirty) {
+      this.writeToDiskSync();
+    }
+  }
+
+  /**
+   * Close the store, ensuring all pending changes are written to disk.
+   * Should be called before the process exits to prevent data loss in batch mode.
+   */
+  close(): void {
+    this.flush();
+  }
+
+  /**
+   * Reload data from disk (useful if file was modified externally)
+   */
+  async reload(): Promise<void> {
+    await this.load();
+  }
+
+  // For debugging
+  size(): number {
+    return this.data.size;
+  }
+
+  dump(): Record<string, unknown>[] {
+    return Array.from(this.data.values());
+  }
+
+  getFilePath(): string {
+    return this.filePath;
+  }
+}

package/src/stores/index.ts

@@ -0,0 +1,6 @@
+export type { StoreAdapter, StoreFilter, StoreConfig } from './types.js';
+export { applyStoreFilter } from './types.js';
+export { MemoryStore } from './memory.js';
+export { FileStore, type FileStoreOptions } from './file.js';
+export { PostgRESTStore, PostgRESTError, type PostgRESTOptions } from './postgrest.js';
+export { createStore, resolveStoreType, type StoreType, type CreateStoreOptions } from './factory.js';