reqon-dsl 0.2.0 → 0.3.0

package/docusaurus/docs/stores/custom-adapters.md

@@ -1,376 +0,0 @@
----
-sidebar_position: 5
----
-
-# Custom Store Adapters
-
-Create custom store adapters to connect Reqon to any storage backend.
-
-## Store Interface
-
-Implement this TypeScript interface:
-
-```typescript
-interface StoreAdapter {
-  // Get a single record by key
-  get(key: string): Promise<Record<string, unknown> | null>;
-
-  // Set a record with key
-  set(key: string, value: Record<string, unknown>): Promise<void>;
-
-  // Update a record (partial update)
-  update(key: string, partial: Record<string, unknown>): Promise<void>;
-
-  // Delete a record by key
-  delete(key: string): Promise<void>;
-
-  // List all records, optionally filtered
-  list(filter?: FilterOptions): Promise<Record<string, unknown>[]>;
-
-  // Clear all records
-  clear(): Promise<void>;
-}
-
-interface FilterOptions {
-  where?: WhereClause[];
-  limit?: number;
-  offset?: number;
-}
-
-interface WhereClause {
-  field: string;
-  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains';
-  value: unknown;
-}
-```
-
-## Basic Example
-
-### Redis Adapter
-
-```typescript
-import { createClient } from 'redis';
-import { StoreAdapter, FilterOptions } from 'reqon';
-
-export class RedisStoreAdapter implements StoreAdapter {
-  private client: ReturnType<typeof createClient>;
-  private prefix: string;
-
-  constructor(url: string, prefix: string) {
-    this.client = createClient({ url });
-    this.prefix = prefix;
-  }
-
-  async connect() {
-    await this.client.connect();
-  }
-
-  private key(id: string) {
-    return `${this.prefix}:${id}`;
-  }
-
-  async get(key: string) {
-    const data = await this.client.get(this.key(key));
-    return data ? JSON.parse(data) : null;
-  }
-
-  async set(key: string, value: Record<string, unknown>) {
-    await this.client.set(this.key(key), JSON.stringify(value));
-  }
-
-  async update(key: string, partial: Record<string, unknown>) {
-    const existing = await this.get(key);
-    if (existing) {
-      await this.set(key, { ...existing, ...partial });
-    }
-  }
-
-  async delete(key: string) {
-    await this.client.del(this.key(key));
-  }
-
-  async list(filter?: FilterOptions) {
-    const keys = await this.client.keys(`${this.prefix}:*`);
-    const items: Record<string, unknown>[] = [];
-
-    for (const key of keys) {
-      const data = await this.client.get(key);
-      if (data) {
-        items.push(JSON.parse(data));
-      }
-    }
-
-    return this.applyFilter(items, filter);
-  }
-
-  async clear() {
-    const keys = await this.client.keys(`${this.prefix}:*`);
-    if (keys.length > 0) {
-      await this.client.del(keys);
-    }
-  }
-
-  private applyFilter(items: Record<string, unknown>[], filter?: FilterOptions) {
-    let result = items;
-
-    if (filter?.where) {
-      result = result.filter(item =>
-        filter.where!.every(clause => this.evaluateClause(item, clause))
-      );
-    }
-
-    if (filter?.offset) {
-      result = result.slice(filter.offset);
-    }
-
-    if (filter?.limit) {
-      result = result.slice(0, filter.limit);
-    }
-
-    return result;
-  }
-
-  private evaluateClause(item: Record<string, unknown>, clause: WhereClause) {
-    const value = item[clause.field];
-
-    switch (clause.operator) {
-      case 'eq': return value === clause.value;
-      case 'neq': return value !== clause.value;
-      case 'gt': return (value as number) > (clause.value as number);
-      case 'gte': return (value as number) >= (clause.value as number);
-      case 'lt': return (value as number) < (clause.value as number);
-      case 'lte': return (value as number) <= (clause.value as number);
-      case 'contains': return String(value).includes(String(clause.value));
-      default: return true;
-    }
-  }
-}
-```
-
-## MongoDB Adapter
-
-```typescript
-import { MongoClient, Db, Collection } from 'mongodb';
-import { StoreAdapter, FilterOptions } from 'reqon';
-
-export class MongoStoreAdapter implements StoreAdapter {
-  private client: MongoClient;
-  private db: Db;
-  private collection: Collection;
-
-  constructor(url: string, database: string, collectionName: string) {
-    this.client = new MongoClient(url);
-    this.db = this.client.db(database);
-    this.collection = this.db.collection(collectionName);
-  }
-
-  async connect() {
-    await this.client.connect();
-  }
-
-  async get(key: string) {
-    const doc = await this.collection.findOne({ _id: key });
-    if (!doc) return null;
-    const { _id, ...data } = doc;
-    return { id: _id, ...data };
-  }
-
-  async set(key: string, value: Record<string, unknown>) {
-    await this.collection.replaceOne(
-      { _id: key },
-      { _id: key, ...value },
-      { upsert: true }
-    );
-  }
-
-  async update(key: string, partial: Record<string, unknown>) {
-    await this.collection.updateOne(
-      { _id: key },
-      { $set: partial }
-    );
-  }
-
-  async delete(key: string) {
-    await this.collection.deleteOne({ _id: key });
-  }
-
-  async list(filter?: FilterOptions) {
-    const query = this.buildQuery(filter?.where);
-    let cursor = this.collection.find(query);
-
-    if (filter?.offset) {
-      cursor = cursor.skip(filter.offset);
-    }
-
-    if (filter?.limit) {
-      cursor = cursor.limit(filter.limit);
-    }
-
-    const docs = await cursor.toArray();
-    return docs.map(({ _id, ...data }) => ({ id: _id, ...data }));
-  }
-
-  async clear() {
-    await this.collection.deleteMany({});
-  }
-
-  private buildQuery(clauses?: WhereClause[]) {
-    if (!clauses || clauses.length === 0) return {};
-
-    const query: Record<string, unknown> = {};
-
-    for (const clause of clauses) {
-      const field = clause.field;
-      switch (clause.operator) {
-        case 'eq': query[field] = clause.value; break;
-        case 'neq': query[field] = { $ne: clause.value }; break;
-        case 'gt': query[field] = { $gt: clause.value }; break;
-        case 'gte': query[field] = { $gte: clause.value }; break;
-        case 'lt': query[field] = { $lt: clause.value }; break;
-        case 'lte': query[field] = { $lte: clause.value }; break;
-        case 'contains': query[field] = { $regex: clause.value }; break;
-      }
-    }
-
-    return query;
-  }
-}
-```
-
-## Registering Custom Adapters
-
-```typescript
-import { execute, registerStoreAdapter } from 'reqon';
-import { RedisStoreAdapter } from './redis-adapter';
-
-// Register the adapter
-registerStoreAdapter('redis', async (name: string, config: any) => {
-  const adapter = new RedisStoreAdapter(config.url, name);
-  await adapter.connect();
-  return adapter;
-});
-
-// Use in mission
-await execute(`
-  mission Test {
-    store cache: redis("my-cache")
-
-    action Fetch {
-      get "/data"
-      store response -> cache { key: .id }
-    }
-
-    run Fetch
-  }
-`, {
-  storeConfig: {
-    redis: {
-      url: 'redis://localhost:6379'
-    }
-  }
-});
-```
-
-## Best Practices
-
-### Connection Management
-
-```typescript
-class MyAdapter implements StoreAdapter {
-  private connected = false;
-
-  async ensureConnected() {
-    if (!this.connected) {
-      await this.connect();
-      this.connected = true;
-    }
-  }
-
-  async get(key: string) {
-    await this.ensureConnected();
-    // ...
-  }
-}
-```
-
-### Error Handling
-
-```typescript
-async set(key: string, value: Record<string, unknown>) {
-  try {
-    await this.client.set(key, value);
-  } catch (error) {
-    throw new StoreError(`Failed to set ${key}: ${error.message}`);
-  }
-}
-```
-
-### Connection Pooling
-
-```typescript
-class PooledAdapter implements StoreAdapter {
-  private pool: Pool;
-
-  constructor(config: PoolConfig) {
-    this.pool = createPool(config);
-  }
-
-  async get(key: string) {
-    const conn = await this.pool.acquire();
-    try {
-      return await conn.get(key);
-    } finally {
-      this.pool.release(conn);
-    }
-  }
-}
-```
-
-### Batch Operations
-
-```typescript
-async setMany(items: Array<{ key: string; value: unknown }>) {
-  // Override for efficient batch writes
-  await this.client.mset(items);
-}
-```
-
-## Testing Adapters
-
-```typescript
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { MyCustomAdapter } from './my-adapter';
-
-describe('MyCustomAdapter', () => {
-  let adapter: MyCustomAdapter;
-
-  beforeEach(async () => {
-    adapter = new MyCustomAdapter(/* config */);
-    await adapter.connect();
-    await adapter.clear();
-  });
-
-  afterEach(async () => {
-    await adapter.clear();
-    await adapter.disconnect();
-  });
-
-  it('should set and get', async () => {
-    await adapter.set('key1', { name: 'test' });
-    const result = await adapter.get('key1');
-    expect(result).toEqual({ name: 'test' });
-  });
-
-  it('should list with filter', async () => {
-    await adapter.set('1', { status: 'active' });
-    await adapter.set('2', { status: 'inactive' });
-
-    const result = await adapter.list({
-      where: [{ field: 'status', operator: 'eq', value: 'active' }]
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].status).toBe('active');
-  });
-});
-```

package/docusaurus/docs/stores/file.md

@@ -1,236 +0,0 @@
----
-sidebar_position: 3
----
-
-# File Store
-
-The file store persists data as JSON files in the `.vague-data` directory.
-
-## Configuration
-
-```vague
-store customers: file("customers")
-store orders: file("orders")
-```
-
-Creates:
-```
-.vague-data/
-├── customers.json
-└── orders.json
-```
-
-## File Structure
-
-Each store is a single JSON file containing an array of records:
-
-```json
-[
-  {"id": "1", "name": "Alice", "email": "alice@example.com"},
-  {"id": "2", "name": "Bob", "email": "bob@example.com"}
-]
-```
-
-When using keys:
-```json
-{
-  "1": {"id": "1", "name": "Alice"},
-  "2": {"id": "2", "name": "Bob"}
-}
-```
-
-## Use Cases
-
-### Local Development
-
-```vague
-mission DevSync {
-  store data: file("dev-data")
-
-  action Sync {
-    get "/items"
-    store response -> data { key: .id }
-  }
-}
-```
-
-### Persistent Cache
-
-```vague
-mission CachedSync {
-  store cache: file("sync-cache")
-
-  action IncrementalSync {
-    get "/items" { since: lastSync }
-    store response -> cache { key: .id, upsert: true }
-  }
-}
-```
-
-### Data Export
-
-```vague
-mission ExportData {
-  store export: file("export")
-
-  action Export {
-    get "/all-data"
-
-    for item in response.data {
-      map item -> ExportFormat { /* ... */ }
-      store item -> export { key: .id }
-    }
-  }
-}
-```
-
-## Custom Directory
-
-```vague
-// Default: .vague-data/
-store data: file("data")
-
-// Custom path (via config)
-store data: file("data", { dir: "./custom-dir" })
-```
-
-Or via CLI:
-
-```bash
-REQON_STATE_DIR=./my-data reqon mission.vague
-```
-
-## Operations
-
-### Write
-
-```vague
-// Simple write
-store response -> data { key: .id }
-
-// Upsert (insert or update)
-store response -> data { key: .id, upsert: true }
-
-// Partial update
-store response -> data { key: .id, partial: true }
-```
-
-### Read
-
-```vague
-// Iterate all
-for item in data { }
-
-// Filter
-for item in data where .status == "active" { }
-```
-
-### Delete
-
-```vague
-// Delete by key
-delete data[item.id]
-
-// Clear all
-clear data
-```
-
-## File Locking
-
-File stores use atomic writes to prevent corruption:
-
-1. Write to temporary file
-2. Rename to target file (atomic)
-3. Delete old file
-
-This ensures data integrity even during crashes.
-
-## Best Practices
-
-### Use Meaningful Names
-
-```vague
-// Good
-store activeCustomers: file("active-customers")
-store invoiceArchive: file("invoice-archive-2024")
-
-// Avoid
-store d: file("d")
-```
-
-### Add to .gitignore
-
-```gitignore
-# Reqon data directory
-.vague-data/
-```
-
-### Use for Development Only
-
-```vague
-mission ConfigurableSync {
-  store data: match env("NODE_ENV") {
-    "production" => sql("items"),
-    _ => file("items-dev")
-  }
-}
-```
-
-### Regular Backups
-
-For important development data:
-
-```bash
-# Backup before major changes
-cp -r .vague-data .vague-data.backup
-```
-
-## Size Considerations
-
-File stores work well for:
-- Up to ~100MB per file
-- Up to ~100,000 records
-
-For larger datasets, consider SQL stores.
-
-### Performance Tips
-
-```vague
-// For large datasets, batch operations
-for batch in chunks(items, 1000) {
-  for item in batch {
-    store item -> data { key: .id }
-  }
-}
-```
-
-## Debugging
-
-### Inspect Files
-
-```bash
-# View raw data
-cat .vague-data/customers.json | jq
-
-# Count records
-cat .vague-data/customers.json | jq 'length'
-```
-
-### Reset Data
-
-```bash
-# Clear specific store
-rm .vague-data/customers.json
-
-# Clear all data
-rm -rf .vague-data/
-```
-
-## Comparison
-
-| Aspect | File Store | Memory Store |
-|--------|-----------|--------------|
-| Persistence | Yes | No |
-| Speed | Fast | Fastest |
-| Scalability | Medium | Limited |
-| Use Case | Development | Testing |