@delma/fylo 1.1.0 → 1.1.1

package/.github/copilot-instructions.md

@@ -1,113 +1,3 @@
-# FYLO — Project Guidelines
+Follow the shared workspace instructions in `../instructions.md` and shared context in `../memory.md`.
 
-## Overview
-
-FYLO (`@vyckr/fylo`) is an S3-backed NoSQL document store with SQL parsing, Redis pub/sub for real-time events, and a CLI. Documents are stored as S3 key paths — not as file contents — with dual key layouts for data access and indexed queries.
-
-**Assume a serverless deployment model** (e.g., AWS Lambda, Cloudflare Workers). This means:
-- No persistent in-memory state across invocations — every request starts cold
-- Distributed coordination (e.g., TTID uniqueness) must use external stores like Redis, not in-process caches
-- Avoid long-lived connections, background threads, or singleton patterns that assume process longevity
-- Keep cold-start overhead minimal — lazy initialization over eager setup
-
-## Architecture
-
-### Key Storage Format
-
-- **Data keys**: `{ttid}/{field}/{value}` — keyed by document ID for full-doc retrieval
-- **Index keys**: `{field}/{value}/{ttid}` — keyed by field for query lookups
-- Nested objects flatten to path segments: `address/city/Toronto`
-- Forward slashes in values are escaped with an ASCII substitute
-
-### Core Modules
-
-| Module | Responsibility |
-|--------|---------------|
-| `src/index.ts` | Main `Fylo` class — CRUD, SQL execution, joins, bulk ops |
-| `src/core/parser.ts` | SQL lexer/parser — tokenizes SQL into query objects |
-| `src/core/query.ts` | Converts `$ops` into glob patterns for S3 key matching |
-| `src/core/walker.ts` | S3 key traversal, document data retrieval, Redis event streaming |
-| `src/core/directory.ts` | Key extraction, reconstruction, rollback tracking |
-| `src/core/format.ts` | Console formatting for query output |
-| `src/adapters/s3.ts` | S3 adapter (Bun S3Client) |
-| `src/adapters/redis.ts` | Redis adapter (Bun RedisClient) |
-| `src/cli/index.ts` | CLI entry point (`fylo.query`) |
-
-### Folder Structure
-
-```
-src/
-  index.ts                # Public API — main Fylo class
-  adapters/               # I/O boundary abstractions (S3, Redis)
-  core/                   # Internal domain logic (parser, query, walker, directory)
-  cli/                    # CLI entry point
-  types/                  # Type declarations (.d.ts only — separate from implementation)
-tests/
-  data.ts                 # Shared test data URLs
-  index.ts                # Test barrel
-  mocks/                  # Mock adapters (S3, Redis) for testing
-  schemas/                # CHEX-generated test schemas (.d.ts + .json)
-  integration/            # End-to-end tests (CRUD, operators, joins, edge cases)
-```
-
-### Dependencies
-
-- **`@vyckr/ttid`** — Time-based unique ID system. `TTID.generate()` creates new IDs; `TTID.generate(existingId)` creates a versioned ID sharing the same creation-time prefix.
-- **`@vyckr/chex`** — Schema validation. Generates `interface` declarations in `.d.ts` files. Generic constraints must use `Record<string, any>` (not `Record<string, unknown>`) to accept these interfaces.
-- **`Bun.Glob`** — Pattern matching for queries. Does NOT support negation extglob `!(pattern)`. Operators like `$ne`, `$gt`, `$lt` use broad globs with post-filtering instead.
-
-## Engineering Standards
-
-- **SOLID principles**: Single responsibility per class/method, depend on abstractions (e.g., S3/Redis adapters), open for extension without modifying core logic
-- **Clean code**: Descriptive naming, small focused functions, no dead code or commented-out blocks, DRY without premature abstraction
-- **Test discipline**: When changing `src/` code, update or add corresponding tests in `tests/` — never leave tests stale after a behaviour change
-- **Error handling**: Fail fast with meaningful errors at system boundaries; use rollback mechanisms for partial writes
-- **No magic values**: Use constants or environment variables; avoid hardcoded strings/numbers in logic
-- **Type safety**: Leverage TypeScript's type system fully — avoid `any` in implementation code, prefer narrow types, and validate at I/O boundaries
-
-## Code Style
-
-- **Runtime**: Bun (ESNext target, ES modules)
-- **Strict TypeScript**: `strict: true`, `noImplicitReturns`, `isolatedModules`
-- **ESLint** enforces `@typescript-eslint/no-explicit-any` in `src/` and `tests/` — use it only in type declarations (`.d.ts`)
-- **No default exports** except the main `Fylo` class
-- Prefer `class` with `static` methods for modules (no standalone functions)
-- Use `_ttid` branded type for document IDs — never plain `string`
-- Prefix internal/test type names with underscore: `_post`, `_album`, `_storeQuery`
-- Type declarations live in `src/types/*.d.ts` — keep separate from implementation
-
-## Build & Test
-
-```bash
-bun test           # Run all tests
-bun run build      # Compile TypeScript
-bun run typecheck  # Type-check without emitting
-bun run lint       # ESLint
-```
-
-- Tests use `bun:test` — `describe`, `test`, `expect`, `mock`, `beforeAll`, `afterAll`
-- S3 and Redis are mocked via `mock.module()` in every test file using `tests/mocks/s3.ts` and `tests/mocks/redis.ts`
-- Test schemas live in `tests/schemas/*.d.ts` as global `interface` declarations (generated by CHEX)
-- Test data URLs are centralized in `tests/data.ts`
-
-## Conventions
-
-- Collection names may contain hyphens (e.g., `ec-test`, `jm-album`) — the parser supports this
-- Nested field access in SQL uses dot notation (`address.city`) which the parser converts to slash-separated paths (`address/city`)
-- `putData` creates documents; `patchDoc` updates them (deletes old keys, writes new ones)
-- `getDocData` retrieves keys for a specific TTID — filters by exact ID, not just prefix
-- Query `$ops` use OR semantics — a document matches if it satisfies at least one operator
-- `$limit` on queries without `$ops` uses S3 `maxKeys`; with `$ops` it post-filters after glob matching
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `BUCKET_PREFIX` | S3 bucket name prefix |
-| `S3_ACCESS_KEY_ID` / `AWS_ACCESS_KEY_ID` | S3 credentials |
-| `S3_SECRET_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` | S3 credentials |
-| `S3_REGION` / `AWS_REGION` | S3 region |
-| `S3_ENDPOINT` / `AWS_ENDPOINT` | S3 endpoint (for compatible stores) |
-| `REDIS_URL` | Redis connection URL |
-| `LOGGING` | Enable debug logging |
-| `STRICT` | Enable schema validation via CHEX |
+If a repo-local instruction file adds stricter rules, follow the repo-local rule.

package/AGENTS.md

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

package/CLAUDE.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delma/fylo",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
   "bin": {
@@ -25,8 +25,8 @@
     "prettier": "^3.0.0"
   },
   "dependencies": {
-    "@vyckr/ttid": "1.3.1",
-    "@vyckr/chex": "0.3.0"
+    "@delma/ttid": "1.3.4",
+    "@delma/chex": "0.3.3"
   },
   "type": "module",
   "peerDependencies": {
@@ -36,7 +36,7 @@
     "type": "git",
     "url": "git+https://github.com/Chidelma/Fylo.git"
   },
-  "homepage": "https://fylo.vyckr.com",
+  "homepage": "https://fylo.del.ma",
   "license": "MIT",
   "keywords": [
     "storage",

package/src/core/directory.ts

@@ -1,5 +1,5 @@
 import { Walker } from "./walker"
-import TTID from "@vyckr/ttid"
+import TTID from "@delma/ttid"
 import { S3 } from "../adapters/s3"
 import { Redis } from "../adapters/redis"
 import { Cipher } from "../adapters/cipher"

package/src/core/format.ts

@@ -1,4 +1,4 @@
-import TTID from '@vyckr/ttid'
+import TTID from '@delma/ttid'
 
 class Format {
   static table(docs: Record<string, any>) {

package/src/core/walker.ts

@@ -1,5 +1,5 @@
 import { S3 } from "../adapters/s3"
-import TTID from "@vyckr/ttid"
+import TTID from "@delma/ttid"
 import { Redis } from "../adapters/redis"
 
 export class Walker {

package/src/index.ts

@@ -2,8 +2,8 @@
 import { Query } from './core/query'
 import { Parser } from './core/parser'
 import { Dir } from "./core/directory";
-import TTID from '@vyckr/ttid';
-import Gen from "@vyckr/chex"
+import TTID from '@delma/ttid';
+import Gen from "@delma/chex"
 import { Walker } from './core/walker';
 import { S3 } from "./adapters/s3"
 import { Cipher } from "./adapters/cipher"

package/src/types/fylo.d.ts

@@ -26,7 +26,7 @@ interface Console {
 
 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>)>
 
-declare module "@vyckr/fylo" {
+declare module "@delma/fylo" {
 
     export default class {
 

package/src/types/index.d.ts

@@ -1,3 +1,3 @@
 /// <reference path="./query.d.ts" />
 /// <reference path="./fylo.d.ts" />
-/// <reference types="@vyckr/ttid" />
+/// <reference types="@delma/ttid" />

package/src/types/vendor-modules.d.ts

@@ -0,0 +1,31 @@
+declare module "@delma/ttid" {
+
+    export type _ttid = string | `${string}-${string}` | `${string}-${string}-${string}`
+
+    export interface _timestamps {
+        createdAt: number
+        updatedAt?: number
+        deletedAt?: number
+    }
+
+    export default class TTID {
+        static isTTID(_id: string): Date | null
+        static isUUID(_id: string): RegExpMatchArray | null
+        static generate(_id?: string, del?: boolean): _ttid
+        static decodeTime(_id: string): _timestamps
+    }
+}
+
+declare module "@delma/chex" {
+
+    export default class Gen {
+        static generateDeclaration(json: unknown, interfaceName?: string): string
+        static sanitizePropertyName(key: string): string
+        static fromJsonString(jsonString: string, interfaceName?: string): string
+        static fromObject(obj: unknown, interfaceName?: string): string
+        static validateData<T extends Record<string, unknown>>(collection: string, data: T): Promise<T>
+    }
+}
+
+type _ttid = import("@delma/ttid")._ttid
+type _timestamps = import("@delma/ttid")._timestamps

package/tests/index.ts

@@ -1,5 +1,5 @@
 import { Redis } from '../src/adapters/redis'
-import ttid from '@vyckr/ttid'
+import ttid from '@delma/ttid'
 
 const redisPub = new Redis()
 const redisSub = new Redis()
@@ -16,4 +16,4 @@ await Bun.sleep(1000)
 
 for await (const data of redisSub.subscribe("bun")) {
     console.log("Received:", data)
-}
+}

package/tests/integration/edge-cases.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
 import Fylo from '../../src'
-import TTID from '@vyckr/ttid'
+import TTID from '@delma/ttid'
 import S3Mock from '../mocks/s3'
 import RedisMock from '../mocks/redis'
 

package/tsconfig.json

@@ -12,8 +12,8 @@
         "noFallthroughCasesInSwitch": true,
         "noImplicitReturns": true,
         "forceConsistentCasingInFileNames": true,
-        "types": ["bun-types", "node", "@vyckr/ttid"],
+        "types": ["bun-types", "node"],
         "isolatedModules": true,
         "skipLibCheck": true
     }
-}
+}