@delma/fylo 1.1.0 → 1.1.2

package/.github/copilot-instructions.md

@@ -1,113 +1,3 @@
-# FYLO — Project Guidelines
+Follow the shared workspace instructions in `../../INSTRUCTIONS.md`, shared context in `../../MEMORY.md`, and shared release process in `../../RELEASE.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/.github/prompts/release.prompt.md

@@ -1,49 +1,10 @@
 ---
-description: "Create a release branch, publish to npm via CI, then merge to main"
+description: "Follow the shared workspace release process"
 agent: "agent"
 tools: [runInTerminal]
 ---
-Create a release branch, publish to npm via CI, then merge to main.
+Follow the shared workspace release process in [../../../RELEASE.md](../../../RELEASE.md).
 
-1. Run `bun test` and stop if any tests fail.
+Use the repo's actual default branch. Do not assume it is `main`.
 
-2. Determine the new version automatically based on unreleased commits:
-   `git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline`
-
-   Apply these rules to select the bump type:
-   - **major** — any commit with a `!` breaking-change marker (e.g. `feat!:`, `fix!:`) or a `BREAKING CHANGE` footer.
-   - **minor** — one or more `feat:` commits and no breaking changes.
-   - **patch** — only `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, or `perf:` commits.
-
-   Compute the new version by incrementing the corresponding part of the current `"version"` in [package.json](package.json) and resetting lower parts to zero. Show the chosen version and the reasoning to the user before proceeding.
-
-3. Update `"version"` in [package.json](package.json) to the new version.
-
-4. Fetch the latest main and create a release branch from it:
-   ```
-   git fetch origin main
-   git checkout -b release/<version> origin/main
-   ```
-
-5. Stage all changes and commit:
-   `git add -A && git commit -m "chore: release v<version>"`
-
-6. Push the branch:
-   `git push -u origin release/<version>`
-
-7. Tell the user that the `publish` workflow will now run on GitHub Actions:
-   - It verifies the branch name matches `package.json` version.
-   - It runs tests, publishes to npm, creates a git tag, and opens a GitHub release.
-   - The NPM_TOKEN secret must be set in repo Settings → Secrets → Actions.
-
-8. Once the workflow passes (user confirms), create a PR and merge it to main:
-   ```
-   gh pr create --title "chore: release v<version>" --body "Release v<version>" --base main --head release/<version>
-   gh pr merge --merge --delete-branch
-   ```
-
-9. Switch back to main and pull:
-   ```
-   git checkout main
-   git pull
-   ```
+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/AGENTS.md

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,3 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delma/fylo",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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
     }
-}
+}

package/.github/prompts/issue.prompt.md

@@ -1,19 +0,0 @@
----
-description: "Create a GitHub issue for a bug or feature request"
-argument-hint: "Describe the bug or feature request"
-agent: "agent"
-tools: [runInTerminal]
----
-Create a GitHub issue. The user's description is provided as the argument.
-
-Determine whether the description sounds like a bug or a feature request, then create the issue with `gh issue create` using the following structure:
-
-**For a bug:**
-- Title: "fix: <short description>"
-- Body sections: **Describe the bug**, **Steps to reproduce**, **Expected behaviour**, **Actual behaviour**, **Possible cause** (reference relevant lines in `src/index.ts` if applicable), **Environment** (Bun version, TypeScript version, AWS/S3 endpoint details).
-
-**For a feature request:**
-- Title: "feat: <short description>"
-- Body sections: **Problem**, **Proposed solution**, **Alternatives considered**, **Affected API** (list any methods in `src/types/fylo.d.ts` or `src/types/query.d.ts` that would change).
-
-Apply the appropriate label (`bug` or `enhancement`) via `--label`. Print the issue URL when done.

package/.github/prompts/pr.prompt.md

@@ -1,18 +0,0 @@
----
-description: "Create a pull request for the current branch into main"
-agent: "agent"
-tools: [runInTerminal]
----
-Create a pull request for the current branch into `main`.
-
-1. Run `git status` and stop if there are uncommitted changes — ask the user to commit or stash them first.
-2. Run `git log main..HEAD --oneline` to list commits on this branch.
-3. Run `git diff main...HEAD` to understand all changes.
-4. Push the branch to origin if it has no upstream: `git push -u origin HEAD`.
-5. Create the PR with `gh pr create` using:
-   - A concise title (≤ 70 chars) derived from the branch name and commits.
-   - A body with three sections:
-     - **Summary** — bullet list of what changed and why.
-     - **Test plan** — checklist of how to verify the changes (reference `bun test` where relevant).
-     - **Breaking changes** — any changes to public API in [src/types/fylo.d.ts](src/types/fylo.d.ts) or [src/types/query.d.ts](src/types/query.d.ts); write "None" if there are none.
-6. Print the PR URL.

package/.github/prompts/review-pr.prompt.md

@@ -1,19 +0,0 @@
----
-description: "Review a pull request by number or URL"
-argument-hint: "PR number or URL (e.g. 42)"
-agent: "agent"
-tools: [runInTerminal]
----
-Review the pull request given as an argument (PR number or URL).
-
-1. Fetch the PR details: `gh pr view <arg> --json title,body,headRefName,baseRefName,files`
-2. Fetch the diff: `gh pr diff <arg>`
-3. Review the changes with focus on:
-   - **Correctness** — logic errors, edge cases missed in query parsing ([src/core/parser.ts](src/core/parser.ts)), S3 operations ([src/adapters/s3.ts](src/adapters/s3.ts)), or directory/index management ([src/core/directory.ts](src/core/directory.ts)).
-   - **Type safety** — use of `any` instead of `unknown`, missing type guards, incorrect use of types in [src/types/](src/types/).
-   - **Tests** — whether new behaviour is covered in [tests/](tests/); flag any missing cases across document, collection, or schema tests.
-   - **Public API** — unintended changes to [src/types/fylo.d.ts](src/types/fylo.d.ts) or [src/types/query.d.ts](src/types/query.d.ts).
-   - **CI** — whether the workflow files in [.github/workflows/](.github/workflows/) are still valid for the change.
-4. Post the review as inline comments using `gh pr review <arg> --comment --body "<feedback>"`.
-   Group feedback by file. Prefix each point with **[suggestion]**, **[issue]**, or **[nit]**.
-5. Summarise the overall verdict: Approve / Request changes / Comment only.

package/.github/prompts/sync-main.prompt.md

@@ -1,14 +0,0 @@
----
-description: "Rebase the current branch onto the latest main from origin"
-agent: "agent"
-tools: [runInTerminal]
----
-Safely bring the current branch up to date with the latest `main` from origin.
-
-1. Confirm the current branch with `git branch --show-current`. If already on `main`, just run `git pull` and stop.
-2. Stash any uncommitted changes with `git stash push -m "sync-main auto-stash"` and note whether anything was stashed.
-3. Fetch the latest: `git fetch origin main`.
-4. Rebase the current branch onto `origin/main`: `git rebase origin/main`.
-5. If the rebase has conflicts, list the conflicting files and stop — ask the user to resolve them, then run `git rebase --continue`.
-6. If a stash was created in step 2, restore it with `git stash pop`.
-7. Report: commits rebased, files changed, any stash restored.