@delma/fylo 2.0.1 → 2.1.1

package/dist/types/fylo.d.ts

@@ -0,0 +1,179 @@
+interface _getDoc {
+    [Symbol.asyncIterator]<T>(): AsyncGenerator<_ttid | Record<_ttid, T>, void, unknown>
+    once<T>(): Promise<Record<_ttid, T>>
+    onDelete(): AsyncGenerator<_ttid, void, unknown>
+}
+
+interface _findDocs {
+    [Symbol.asyncIterator]<T>(): AsyncGenerator<
+        _ttid | Record<_ttid, T> | Record<string, _ttid[]> | Record<_ttid, Partial<T>> | undefined,
+        void,
+        unknown
+    >
+    collect<T>(): AsyncGenerator<
+        _ttid | Record<_ttid, T> | Record<string, _ttid[]> | Record<_ttid, Partial<T>> | undefined,
+        void,
+        unknown
+    >
+    onDelete(): AsyncGenerator<_ttid, void, unknown>
+}
+
+interface ObjectConstructor {
+    appendGroup: (target: Record<string, any>, source: Record<string, any>) => Record<string, any>
+}
+
+interface Console {
+    format: (docs: Record<string, any>) => void
+}
+
+type _joinDocs<T, U> =
+    | _ttid[]
+    | Record<string, _ttid[]>
+    | Record<string, Record<_ttid, Partial<T | U>>>
+    | Record<`${_ttid}, ${_ttid}`, T | U | (T & U) | (Partial<T> & Partial<U>)>
+
+type _fyloSyncMode = 'await-sync' | 'fire-and-forget'
+
+interface _fyloWriteSyncEvent<T extends Record<string, any> = Record<string, any>> {
+    operation: 'put' | 'patch'
+    collection: string
+    docId: _ttid
+    previousDocId?: _ttid
+    path: string
+    data: T
+}
+
+interface _fyloDeleteSyncEvent {
+    operation: 'delete' | 'patch'
+    collection: string
+    docId: _ttid
+    path: string
+}
+
+interface _fyloSyncHooks<T extends Record<string, any> = Record<string, any>> {
+    onWrite?: (event: _fyloWriteSyncEvent<T>) => Promise<void> | void
+    onDelete?: (event: _fyloDeleteSyncEvent) => Promise<void> | void
+}
+
+interface _fyloOptions {
+    root?: string
+    s3FilesRoot?: string
+    sync?: _fyloSyncHooks
+    syncMode?: _fyloSyncMode
+}
+
+interface _importBulkDataOptions {
+    limit?: number
+    maxBytes?: number
+    allowedProtocols?: string[]
+    allowedHosts?: string[]
+    allowPrivateNetwork?: boolean
+}
+
+declare module '@delma/fylo' {
+    export class FyloSyncError extends Error {
+        readonly collection: string
+        readonly docId: _ttid
+        readonly path: string
+        readonly operation: string
+    }
+
+    export type FyloSyncMode = _fyloSyncMode
+    export type FyloWriteSyncEvent<T extends Record<string, any> = Record<string, any>> =
+        _fyloWriteSyncEvent<T>
+    export type FyloDeleteSyncEvent = _fyloDeleteSyncEvent
+    export type FyloSyncHooks<T extends Record<string, any> = Record<string, any>> =
+        _fyloSyncHooks<T>
+    export type FyloOptions = _fyloOptions
+    export type ImportBulkDataOptions = _importBulkDataOptions
+
+    export default class {
+        constructor(options?: _fyloOptions)
+
+        /**
+         * Compatibility helper. FYLO now writes synchronously to the filesystem,
+         * so rollback is a no-op.
+         */
+        rollback(): Promise<void>
+
+        /**
+         * Executes a SQL query and returns the results.
+         * @param SQL The SQL query to execute.
+         * @returns The results of the query.
+         */
+        executeSQL<T extends Record<string, any>, U extends Record<string, any> = {}>(
+            SQL: string
+        ): Promise<number | void | any[] | _ttid | Record<any, any>>
+
+        static createCollection(collection: string): Promise<void>
+        static dropCollection(collection: string): Promise<void>
+
+        createCollection(collection: string): Promise<void>
+        dropCollection(collection: string): Promise<void>
+
+        importBulkData(
+            collection: string,
+            url: URL,
+            limitOrOptions?: number | _importBulkDataOptions
+        ): Promise<number>
+
+        exportBulkData<T extends Record<string, any>>(
+            collection: string
+        ): AsyncGenerator<T, void, unknown>
+
+        static exportBulkData<T extends Record<string, any>>(
+            collection: string
+        ): AsyncGenerator<T, void, unknown>
+
+        static getDoc(collection: string, _id: _ttid, onlyId?: boolean): _getDoc
+
+        getDoc(collection: string, _id: _ttid, onlyId?: boolean): _getDoc
+
+        batchPutData<T extends Record<string, any>>(
+            collection: string,
+            batch: Array<T>
+        ): Promise<_ttid[]>
+
+        putData<T extends Record<string, any>>(collection: string, data: T): Promise<_ttid>
+        putData<T extends Record<string, any>>(
+            collection: string,
+            data: Record<_ttid, T>
+        ): Promise<_ttid>
+
+        patchDoc<T extends Record<string, any>>(
+            collection: string,
+            newDoc: Record<_ttid, Partial<T>>,
+            oldDoc?: Record<_ttid, T>
+        ): Promise<_ttid>
+
+        patchDocs<T extends Record<string, any>>(
+            collection: string,
+            updateSchema: _storeUpdate<T>
+        ): Promise<number>
+
+        delDoc(collection: string, _id: _ttid): Promise<void>
+
+        delDocs<T extends Record<string, any>>(
+            collection: string,
+            deleteSchema?: _storeDelete<T>
+        ): Promise<number>
+
+        static joinDocs<T extends Record<string, any>, U extends Record<string, any>>(
+            join: _join<T, U>
+        ): Promise<_joinDocs<T, U>>
+
+        joinDocs<T extends Record<string, any>, U extends Record<string, any>>(
+            join: _join<T, U>
+        ): Promise<_joinDocs<T, U>>
+
+        static findDocs<T extends Record<string, any>>(
+            collection: string,
+            query?: _storeQuery<T>
+        ): _findDocs
+
+        findDocs<T extends Record<string, any>>(
+            collection: string,
+            query?: _storeQuery<T>
+        ): _findDocs
+    }
+}

package/{src → dist}/types/node-runtime.d.ts

@@ -1,5 +1,6 @@
 declare const process: {
     env: Record<string, string | undefined>
+    cwd(): string
 }
 
 declare const Buffer: {

package/package.json

@@ -1,18 +1,15 @@
 {
   "name": "@delma/fylo",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
   "bin": {
-    "fylo.query": "./dist/cli/index.js",
-    "fylo.worker": "./dist/worker.js",
-    "fylo.migrate": "./dist/migrate-cli.js"
+    "fylo.query": "./dist/cli/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist && tsc && mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
     "test": "bun test",
     "typecheck": "tsc -p tsconfig.typecheck.json",
-    "worker": "bun run ./src/worker.ts",
     "lint": "prettier --check \"src/**/*.{ts,d.ts}\" \"tests/**/*.js\" README.md",
     "format": "prettier --write src tests"
   },

package/.env.example

@@ -1,16 +0,0 @@
-LOGGING=
-STRICT=
-S3_REGION=ca-central-1
-S3_ACCESS_KEY_ID=HELLO
-S3_SECRET_ACCESS_KEY=WORLD
-S3_ENDPOINT=https//example.com
-BUCKET_PREFIX="byos-test"
-SCHEMA_DIR=/path/to/schema/dir
-REDIS_URL=redis://localhost:6379
-REDIS_CONN_TIMEOUT=5000
-REDIS_IDLE_TIMEOUT=30000
-REDIS_AUTO_RECONNECT=
-REDIS_MAX_RETRIES=10
-REDIS_ENABLE_OFFLINE_QUEUE=
-REDIS_ENABLE_AUTO_PIPELINING=
-REDIS_TLS=

package/.github/copilot-instructions.md

@@ -1,3 +0,0 @@
-Follow the shared workspace instructions in `../../INSTRUCTIONS.md`, shared context in `../../MEMORY.md`, and shared release process in `../../RELEASE.md`.
-
-If a repo-local instruction file adds stricter rules, follow the repo-local rule.

package/.github/prompts/release.prompt.md

@@ -1,10 +0,0 @@
----
-description: "Follow the shared workspace release process"
-agent: "agent"
-tools: [runInTerminal]
----
-Follow the shared workspace release process in [../../../RELEASE.md](../../../RELEASE.md).
-
-Use the repo's actual default branch. Do not assume it is `main`.
-
-If repo-local workflows impose stricter checks or branch requirements, follow the repo-local workflow and then update the shared release guide later if that rule becomes the new standard.

package/.github/workflows/ci.yml

@@ -1,37 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [release/*]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    name: Test (Bun ${{ matrix.bun-version }})
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        bun-version: [latest, 1.2.x]
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ matrix.bun-version }}
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Type check
-        run: bun run typecheck
-
-      - name: Lint
-        run: bun run lint
-
-      - name: Run tests
-        run: bun test

package/.github/workflows/publish.yml

@@ -1,91 +0,0 @@
-name: Publish
-
-on:
-  push:
-    branches: [release/*]
-
-jobs:
-  test:
-    name: Test before publish
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Type check
-        run: bun run typecheck
-
-      - name: Lint
-        run: bun run lint
-
-      - name: Run tests
-        run: bun test
-
-  publish:
-    name: Publish to npm
-    runs-on: ubuntu-latest
-    needs: test
-    permissions:
-      contents: write   # create git tags
-      id-token: write   # npm provenance
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Setup Node and upgrade npm
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Upgrade npm
-        run: npm install -g npm@latest
-
-      - name: Resolve version from branch
-        id: version
-        run: |
-          BRANCH="${GITHUB_REF#refs/heads/}"
-          VERSION="${BRANCH#release/}"
-          PKG_VERSION=$(bun -e "console.log(require('./package.json').version)")
-          if [ "$VERSION" != "$PKG_VERSION" ]; then
-            echo "Branch version ($VERSION) does not match package.json ($PKG_VERSION). Skipping publish."
-            exit 1
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Publish to npm (Trusted Publishing via OIDC)
-        run: |
-          echo "registry=https://registry.npmjs.org/" >> ~/.npmrc
-          npm publish --access public --provenance
-
-      - name: Create and push version tag
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -f -a "v${{ steps.version.outputs.version }}" -m "v${{ steps.version.outputs.version }}"
-          git push origin "v${{ steps.version.outputs.version }}" --force
-
-      - name: Create GitHub release
-        run: |
-          gh release create "v${{ steps.version.outputs.version }}" \
-            --title "v${{ steps.version.outputs.version }}" \
-            --generate-notes
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.prettierrc

@@ -1,7 +0,0 @@
-{
-    "semi": false,
-    "singleQuote": true,
-    "tabWidth": 4,
-    "trailingComma": "none",
-    "printWidth": 100
-}

package/AGENTS.md

@@ -1,3 +0,0 @@
-Follow the shared workspace instructions in [../INSTRUCTIONS.md](../INSTRUCTIONS.md), shared context in [../MEMORY.md](../MEMORY.md), and shared release process in [../RELEASE.md](../RELEASE.md).
-
-Repo-local rules may add to or override the shared files when explicitly stated.

package/CLAUDE.md

@@ -1,3 +0,0 @@
-Follow the shared workspace instructions in [../INSTRUCTIONS.md](../INSTRUCTIONS.md), shared context in [../MEMORY.md](../MEMORY.md), and shared release process in [../RELEASE.md](../RELEASE.md).
-
-Repo-local rules may add to or override the shared files when explicitly stated.

package/eslint.config.js

@@ -1,32 +0,0 @@
-import tsPlugin from '@typescript-eslint/eslint-plugin'
-import tsParser from '@typescript-eslint/parser'
-import prettierConfig from 'eslint-config-prettier'
-
-export default [
-    {
-        files: ['src/**/*.ts'],
-        languageOptions: {
-            parser: tsParser,
-            parserOptions: {}
-        },
-        plugins: {
-            '@typescript-eslint': tsPlugin
-        },
-        rules: {
-            ...tsPlugin.configs['recommended'].rules,
-            '@typescript-eslint/no-explicit-any': 'warn',
-            '@typescript-eslint/explicit-function-return-type': 'warn',
-            '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
-        }
-    },
-    {
-        files: ['tests/**/*.js'],
-        rules: {
-            'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
-        }
-    },
-    prettierConfig,
-    {
-        ignores: ['bin/**', 'node_modules/**', '**/*.d.ts']
-    }
-]

package/src/CLI

@@ -1,39 +0,0 @@
-#!/usr/bin/env bun
-/// <reference path="./types/index.d.ts" />
-import Silo from '.'
-
-const SQL = process.argv[process.argv.length - 1]
-
-const op = SQL.match(
-    /^((?:SELECT|select)|(?:INSERT|insert)|(?:UPDATE|update)|(?:DELETE|delete)|(?:CREATE|create)|(?:DROP|drop))/i
-)
-
-if (!op) throw new Error('Missing SQL Operation')
-
-const res = await new Silo().executeSQL(SQL)
-
-const cmnd = op.shift()!
-
-switch (cmnd.toUpperCase()) {
-    case 'CREATE':
-        console.log('Successfully created schema')
-        break
-    case 'DROP':
-        console.log('Successfully dropped schema')
-        break
-    case 'SELECT':
-        if (typeof res === 'object' && !Array.isArray(res)) console.format(res)
-        else console.log(res)
-        break
-    case 'INSERT':
-        console.log(res)
-        break
-    case 'UPDATE':
-        console.log(`Successfully updated ${res} document(s)`)
-        break
-    case 'DELETE':
-        console.log(`Successfully deleted ${res} document(s)`)
-        break
-    default:
-        throw new Error('Invalid Operation: ' + cmnd)
-}

package/src/adapters/cipher.ts

@@ -1,180 +0,0 @@
-/**
- * AES-256-CBC encryption adapter for field-level value encryption.
- *
- * Two modes are supported via the `deterministic` flag on `encrypt()`:
- *
- * - **Random IV (default)**: A cryptographically random IV is generated per
- *   encryption operation. Identical plaintexts produce different ciphertexts.
- *   Use this for fields that do not need exact-match ($eq/$ne) queries.
- *
- * - **Deterministic IV (opt-in)**: The IV is derived from HMAC-SHA256 of the
- *   plaintext, so identical values always produce identical ciphertext. This
- *   enables exact-match queries on encrypted fields but leaks equality — an
- *   observer can determine which records share field values without decrypting.
- *   Use only when $eq/$ne queries on encrypted fields are required.
- *
- * Encrypted fields are declared per-collection in JSON schema files via the
- * `$encrypted` array. The encryption key is sourced from `ENCRYPTION_KEY` env var.
- * Set `CIPHER_SALT` to a unique random value to prevent cross-deployment attacks.
- */
-
-export class Cipher {
-    private static key: CryptoKey | null = null
-    private static hmacKey: CryptoKey | null = null
-
-    /** Per-collection encrypted field sets, loaded from schema `$encrypted` arrays. */
-    private static collections: Map<string, Set<string>> = new Map()
-
-    static isConfigured(): boolean {
-        return Cipher.key !== null
-    }
-
-    static hasEncryptedFields(collection: string): boolean {
-        const fields = Cipher.collections.get(collection)
-        return !!fields && fields.size > 0
-    }
-
-    static isEncryptedField(collection: string, field: string): boolean {
-        const fields = Cipher.collections.get(collection)
-        if (!fields || fields.size === 0) return false
-
-        for (const pattern of fields) {
-            if (field === pattern) return true
-            // Support nested: encrypting "address" encrypts "address/city" etc.
-            if (field.startsWith(`${pattern}/`)) return true
-        }
-
-        return false
-    }
-
-    /**
-     * Registers encrypted fields for a collection (from schema `$encrypted` array).
-     */
-    static registerFields(collection: string, fields: string[]): void {
-        if (fields.length > 0) {
-            Cipher.collections.set(collection, new Set(fields))
-        }
-    }
-
-    /**
-     * Derives AES + HMAC keys from a secret string. Called once at startup.
-     */
-    static async configure(secret: string): Promise<void> {
-        const encoder = new TextEncoder()
-        const keyMaterial = await crypto.subtle.importKey(
-            'raw',
-            encoder.encode(secret),
-            'PBKDF2',
-            false,
-            ['deriveBits']
-        )
-
-        const cipherSalt = process.env.CIPHER_SALT
-        if (!cipherSalt) {
-            console.warn(
-                'CIPHER_SALT is not set. Using default salt is insecure for multi-deployment use. Set CIPHER_SALT to a unique random value.'
-            )
-        }
-
-        // Derive 48 bytes: 32 for AES key + 16 for HMAC key
-        const bits = await crypto.subtle.deriveBits(
-            {
-                name: 'PBKDF2',
-                salt: encoder.encode(cipherSalt ?? 'fylo-cipher'),
-                iterations: 100000,
-                hash: 'SHA-256'
-            },
-            keyMaterial,
-            384
-        )
-
-        const derived = new Uint8Array(bits)
-
-        Cipher.key = await crypto.subtle.importKey(
-            'raw',
-            derived.slice(0, 32),
-            { name: 'AES-CBC' },
-            false,
-            ['encrypt', 'decrypt']
-        )
-
-        Cipher.hmacKey = await crypto.subtle.importKey(
-            'raw',
-            derived.slice(32),
-            { name: 'HMAC', hash: 'SHA-256' },
-            false,
-            ['sign']
-        )
-    }
-
-    static reset(): void {
-        Cipher.key = null
-        Cipher.hmacKey = null
-        Cipher.collections = new Map()
-    }
-
-    /**
-     * Deterministic IV from HMAC-SHA256 of plaintext, truncated to 16 bytes.
-     */
-    private static async deriveIV(plaintext: string): Promise<Uint8Array> {
-        const encoder = new TextEncoder()
-        const sig = await crypto.subtle.sign('HMAC', Cipher.hmacKey!, encoder.encode(plaintext))
-        return new Uint8Array(sig).slice(0, 16)
-    }
-
-    /**
-     * Encrypts a value. Returns a URL-safe base64 string (no slashes).
-     *
-     * @param value - The plaintext to encrypt.
-     * @param deterministic - When true, derives IV from HMAC of plaintext (same
-     *   input always produces same ciphertext). Required for $eq/$ne queries on
-     *   encrypted fields. Defaults to false (random IV per operation).
-     */
-    static async encrypt(value: string, deterministic = false): Promise<string> {
-        if (!Cipher.key) throw new Error('Cipher not configured — set ENCRYPTION_KEY env var')
-
-        const iv = deterministic
-            ? await Cipher.deriveIV(value)
-            : crypto.getRandomValues(new Uint8Array(16))
-        const encoder = new TextEncoder()
-
-        const encrypted = await crypto.subtle.encrypt(
-            { name: 'AES-CBC', iv: iv as any },
-            Cipher.key,
-            encoder.encode(value)
-        )
-
-        // Concatenate IV + ciphertext and encode as URL-safe base64
-        const combined = new Uint8Array(iv.length + encrypted.byteLength)
-        combined.set(iv)
-        combined.set(new Uint8Array(encrypted), iv.length)
-
-        return btoa(String.fromCharCode(...combined))
-            .replace(/\+/g, '-')
-            .replace(/\//g, '_')
-            .replace(/=+$/, '')
-    }
-
-    /**
-     * Decrypts a URL-safe base64 encoded value back to plaintext.
-     */
-    static async decrypt(encoded: string): Promise<string> {
-        if (!Cipher.key) throw new Error('Cipher not configured — set ENCRYPTION_KEY env var')
-
-        // Restore standard base64
-        const b64 = encoded.replace(/-/g, '+').replace(/_/g, '/')
-        const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4)
-
-        const combined = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0))
-        const iv = combined.slice(0, 16)
-        const ciphertext = combined.slice(16)
-
-        const decrypted = await crypto.subtle.decrypt(
-            { name: 'AES-CBC', iv },
-            Cipher.key,
-            ciphertext
-        )
-
-        return new TextDecoder().decode(decrypted)
-    }
-}