@delma/fylo 1.0.0

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

@@ -0,0 +1,232 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import TTID from '@vyckr/ttid'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+/**
+ * Edge case coverage:
+ *   - Non-existent ID returns empty object
+ *   - Values containing forward slashes survive the SLASH_ASCII (%2F) round-trip
+ *   - Multiple $ops entries act as OR (union across patterns)
+ *   - $rename renames fields in query output
+ *   - Versioned putData (existing TTID as key) preserves the creation-time prefix
+ *   - SQL UPDATE ONE — update a single document by ID via SQL
+ *   - SQL DELETE ONE — delete a single document by ID via SQL
+ */
+
+const COLLECTION = 'ec-test'
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(COLLECTION)
+})
+
+afterAll(async () => {
+    await Fylo.dropCollection(COLLECTION)
+})
+
+describe("NO-SQL", () => {
+
+    test("GET ONE — non-existent ID returns empty object", async () => {
+
+        const fakeId = TTID.generate() as _ttid
+
+        const result = await Fylo.getDoc(COLLECTION, fakeId).once()
+
+        expect(Object.keys(result).length).toBe(0)
+    })
+
+    test("PUT / GET — forward slashes in values round-trip correctly", async () => {
+
+        const original = {
+            userId: 1,
+            id: 1,
+            title: 'Slash Test',
+            body: 'https://example.com/api/v1/resource'
+        }
+
+        const _id = await fylo.putData<_post>(COLLECTION, original)
+
+        const result = await Fylo.getDoc<_post>(COLLECTION, _id).once()
+        const doc = result[_id]
+
+        expect(doc.body).toBe(original.body)
+
+        await fylo.delDoc(COLLECTION, _id)
+    })
+
+    test("PUT / GET — values with multiple consecutive slashes round-trip correctly", async () => {
+
+        const original = {
+            userId: 1,
+            id: 2,
+            title: 'Double Slash',
+            body: 'https://cdn.example.com//assets//image.png'
+        }
+
+        const _id = await fylo.putData<_post>(COLLECTION, original)
+
+        const result = await Fylo.getDoc<_post>(COLLECTION, _id).once()
+
+        expect(result[_id].body).toBe(original.body)
+
+        await fylo.delDoc(COLLECTION, _id)
+    })
+
+    test("$ops — multiple conditions act as OR union", async () => {
+
+        const cleanFylo = new Fylo()
+
+        const id1 = await cleanFylo.putData<_post>(COLLECTION, { userId: 10, id: 100, title: 'Alpha', body: 'first' })
+        const id2 = await cleanFylo.putData<_post>(COLLECTION, { userId: 20, id: 200, title: 'Beta',  body: 'second' })
+
+        const results: Record<_ttid, _post> = {}
+
+        for await (const data of Fylo.findDocs<_post>(COLLECTION, {
+            $ops: [
+                { userId: { $eq: 10 } },
+                { userId: { $eq: 20 } }
+            ]
+        }).collect()) {
+            Object.assign(results, data)
+        }
+
+        expect(results[id1]).toBeDefined()
+        expect(results[id2]).toBeDefined()
+
+        await cleanFylo.delDoc(COLLECTION, id1)
+        await cleanFylo.delDoc(COLLECTION, id2)
+    })
+
+    test("$rename — renames fields in query output", async () => {
+
+        const cleanFylo = new Fylo()
+
+        const _id = await cleanFylo.putData<_post>(COLLECTION, {
+            userId: 1,
+            id: 300,
+            title: 'Rename Me',
+            body: 'some body'
+        })
+
+        let renamed: Partial<_post> & { name?: string } = {}
+
+        for await (const data of Fylo.findDocs<_post>(COLLECTION, {
+            $ops: [{ id: { $eq: 300 } }],
+            $rename: { title: 'name' } as Record<keyof Partial<_post>, string>
+        }).collect()) {
+            renamed = Object.values(data as Record<_ttid, typeof renamed>)[0]
+        }
+
+        expect(renamed.name).toBe('Rename Me')
+        expect(renamed.title).toBeUndefined()
+
+        await cleanFylo.delDoc(COLLECTION, _id)
+    })
+
+    test("versioned putData — preserves creation-time prefix in TTID", async () => {
+
+        const cleanFylo = new Fylo()
+
+        const _id1 = await cleanFylo.putData<_post>(COLLECTION, {
+            userId: 1,
+            id: 400,
+            title: 'Original',
+            body: 'v1'
+        })
+
+        const _id2 = await cleanFylo.putData<_post>(COLLECTION, {
+            [_id1]: { userId: 1, id: 400, title: 'Updated', body: 'v2' }
+        })
+
+        // The creation-time segment (before the first '-') must be identical
+        expect(_id2.split('-')[0]).toBe(_id1.split('-')[0])
+
+        // The updated doc is retrievable via its own TTID
+        const result = await Fylo.getDoc<_post>(COLLECTION, _id2).once()
+        const doc = result[_id2]
+
+        expect(doc).toBeDefined()
+        expect(doc.title).toBe('Updated')
+
+        // Clean up both versions
+        await cleanFylo.delDoc(COLLECTION, _id1)
+        await cleanFylo.delDoc(COLLECTION, _id2)
+    })
+
+    test("versioned putData — original version is no longer retrievable by old full TTID", async () => {
+
+        const cleanFylo = new Fylo()
+
+        const _id1 = await cleanFylo.putData<_post>(COLLECTION, {
+            userId: 1,
+            id: 500,
+            title: 'Old Version',
+            body: 'original'
+        })
+
+        const _id2 = await cleanFylo.putData<_post>(COLLECTION, {
+            [_id1]: { userId: 1, id: 500, title: 'New Version', body: 'updated' }
+        })
+
+        // Both IDs are different (update appended a segment)
+        expect(_id1).not.toBe(_id2)
+
+        await cleanFylo.delDoc(COLLECTION, _id2)
+    })
+})
+
+describe("SQL", () => {
+
+    test("UPDATE ONE — update a single document by querying its unique field", async () => {
+
+        const cleanFylo = new Fylo()
+
+        await cleanFylo.putData<_post>(COLLECTION, {
+            userId: 1,
+            id: 600,
+            title: 'Before SQL Update',
+            body: 'original'
+        })
+
+        const updated = await cleanFylo.executeSQL<_post>(
+            `UPDATE ${COLLECTION} SET title = 'After SQL Update' WHERE id = 600`
+        ) as number
+
+        expect(updated).toBe(1)
+
+        const results = await cleanFylo.executeSQL<_post>(
+            `SELECT * FROM ${COLLECTION} WHERE title = 'After SQL Update'`
+        ) as Record<_ttid, _post>
+
+        expect(Object.keys(results).length).toBe(1)
+        expect(Object.values(results)[0].title).toBe('After SQL Update')
+    })
+
+    test("DELETE ONE — delete a single document by querying its unique field", async () => {
+
+        const cleanFylo = new Fylo()
+
+        await cleanFylo.putData<_post>(COLLECTION, {
+            userId: 1,
+            id: 700,
+            title: 'Delete Via SQL',
+            body: 'should be removed'
+        })
+
+        await cleanFylo.executeSQL<_post>(
+            `DELETE FROM ${COLLECTION} WHERE title = 'Delete Via SQL'`
+        )
+
+        const results = await cleanFylo.executeSQL<_post>(
+            `SELECT * FROM ${COLLECTION} WHERE title = 'Delete Via SQL'`
+        ) as Record<_ttid, _post>
+
+        expect(Object.keys(results).length).toBe(0)
+    })
+})

package/tests/integration/encryption.test.ts

@@ -0,0 +1,176 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+import { CipherMock } from '../mocks/cipher'
+
+const COLLECTION = 'encrypted-test'
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+mock.module('../../src/adapters/cipher', () => ({ Cipher: CipherMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(COLLECTION)
+    await CipherMock.configure('test-secret-key')
+    CipherMock.registerFields(COLLECTION, ['email', 'ssn', 'address'])
+})
+
+afterAll(async () => {
+    CipherMock.reset()
+    await Fylo.dropCollection(COLLECTION)
+})
+
+describe("Encryption", () => {
+
+    let docId: _ttid
+
+    test("PUT encrypted document", async () => {
+
+        docId = await fylo.putData(COLLECTION, {
+            name: 'Alice',
+            email: 'alice@example.com',
+            ssn: '123-45-6789',
+            age: 30
+        })
+
+        expect(docId).toBeDefined()
+    })
+
+    test("GET decrypts fields transparently", async () => {
+
+        const result = await Fylo.getDoc(COLLECTION, docId).once()
+        const doc = Object.values(result)[0]
+
+        expect(doc.name).toBe('Alice')
+        expect(doc.email).toBe('alice@example.com')
+        expect(doc.ssn).toBe('123-45-6789')
+        expect(doc.age).toBe(30)
+    })
+
+    test("encrypted values stored in S3 keys are not plaintext", () => {
+
+        const bucket = S3Mock.getBucketFormat(COLLECTION)
+
+        // Verify the bucket was created and doc round-trip works
+        // (plaintext values should not appear as raw key segments)
+        expect(bucket).toBeDefined()
+    })
+
+    test("$eq query works on encrypted field", async () => {
+
+        let found = false
+
+        for await (const data of Fylo.findDocs(COLLECTION, {
+            $ops: [{ email: { $eq: 'alice@example.com' } }]
+        }).collect()) {
+
+            if(typeof data === 'object') {
+                const doc = Object.values(data)[0]
+                expect(doc.email).toBe('alice@example.com')
+                found = true
+            }
+        }
+
+        expect(found).toBe(true)
+    })
+
+    test("$ne throws on encrypted field", async () => {
+
+        try {
+            const iter = Fylo.findDocs(COLLECTION, {
+                $ops: [{ email: { $ne: 'bob@example.com' } }]
+            }).collect()
+            await iter.next()
+            expect(true).toBe(false) // Should not reach here
+        } catch (e) {
+            expect((e as Error).message).toContain('not supported on encrypted field')
+        }
+    })
+
+    test("$gt throws on encrypted field", async () => {
+
+        try {
+            const iter = Fylo.findDocs(COLLECTION, {
+                $ops: [{ ssn: { $gt: 0 } }]
+            }).collect()
+            await iter.next()
+            expect(true).toBe(false)
+        } catch (e) {
+            expect((e as Error).message).toContain('not supported on encrypted field')
+        }
+    })
+
+    test("$like throws on encrypted field", async () => {
+
+        try {
+            const iter = Fylo.findDocs(COLLECTION, {
+                $ops: [{ email: { $like: '%@example.com' } }]
+            }).collect()
+            await iter.next()
+            expect(true).toBe(false)
+        } catch (e) {
+            expect((e as Error).message).toContain('not supported on encrypted field')
+        }
+    })
+
+    test("non-encrypted fields remain queryable with all operators", async () => {
+
+        let found = false
+
+        for await (const data of Fylo.findDocs(COLLECTION, {
+            $ops: [{ name: { $eq: 'Alice' } }]
+        }).collect()) {
+
+            if(typeof data === 'object') {
+                const doc = Object.values(data)[0]
+                expect(doc.name).toBe('Alice')
+                found = true
+            }
+        }
+
+        expect(found).toBe(true)
+    })
+
+    test("nested encrypted field (address.city)", async () => {
+
+        const id = await fylo.putData(COLLECTION, {
+            name: 'Bob',
+            email: 'bob@example.com',
+            ssn: '987-65-4321',
+            age: 25,
+            address: { city: 'Toronto', zip: 'M5V 2T6' }
+        })
+
+        const result = await Fylo.getDoc(COLLECTION, id).once()
+        const doc = Object.values(result)[0]
+
+        expect(doc.address.city).toBe('Toronto')
+        expect(doc.address.zip).toBe('M5V 2T6')
+    })
+
+    test("UPDATE preserves encryption", async () => {
+
+        await fylo.patchDoc(COLLECTION, {
+            [docId]: { email: 'alice-new@example.com' }
+        } as Record<_ttid, Record<string, string>>)
+
+        // Find the updated doc (patchDoc generates new TTID)
+        let found = false
+
+        for await (const data of Fylo.findDocs(COLLECTION, {
+            $ops: [{ email: { $eq: 'alice-new@example.com' } }]
+        }).collect()) {
+
+            if(typeof data === 'object') {
+                const doc = Object.values(data)[0]
+                expect(doc.email).toBe('alice-new@example.com')
+                found = true
+            }
+        }
+
+        expect(found).toBe(true)
+    })
+})

package/tests/integration/export.test.ts

@@ -0,0 +1,61 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import { postsURL } from '../data'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+const POSTS = 'exp-post'
+const IMPORT_LIMIT = 20
+
+let importedCount = 0
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(POSTS)
+    try {
+        importedCount = await fylo.importBulkData<_post>(POSTS, new URL(postsURL), IMPORT_LIMIT)
+    } catch {
+        await fylo.rollback()
+    }
+})
+
+afterAll(async () => {
+    await Fylo.dropCollection(POSTS)
+})
+
+describe("NO-SQL", () => {
+
+    test("EXPORT count matches import", async () => {
+
+        let exported = 0
+
+        for await (const _doc of Fylo.exportBulkData<_post>(POSTS)) {
+            exported++
+        }
+
+        expect(exported).toBe(importedCount)
+    })
+
+    test("EXPORT document shape", async () => {
+
+        for await (const doc of Fylo.exportBulkData<_post>(POSTS)) {
+            expect(doc).toHaveProperty('title')
+            expect(doc).toHaveProperty('userId')
+            expect(doc).toHaveProperty('body')
+            break
+        }
+    })
+
+    test("EXPORT all documents are valid posts", async () => {
+
+        for await (const doc of Fylo.exportBulkData<_post>(POSTS)) {
+            expect(typeof doc.title).toBe('string')
+            expect(typeof doc.userId).toBe('number')
+            expect(doc.userId).toBeGreaterThan(0)
+        }
+    })
+})

package/tests/integration/join-modes.test.ts

@@ -0,0 +1,221 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import { albumURL, postsURL } from '../data'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+/**
+ * Albums (userId 1–10) and posts (userId 1–10) share a userId field,
+ * making them a natural fit for join tests across all four join modes.
+ *
+ * Join semantics in Fylo:
+ *   inner  → only the join field values
+ *   left   → full left-collection document
+ *   right  → full right-collection document
+ *   outer  → merged left + right documents
+ */
+
+const ALBUMS = 'jm-album'
+const POSTS  = 'jm-post'
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Promise.all([Fylo.createCollection(ALBUMS), Fylo.createCollection(POSTS)])
+    try {
+        await Promise.all([
+            fylo.importBulkData<_album>(ALBUMS, new URL(albumURL), 100),
+            fylo.importBulkData<_post>(POSTS, new URL(postsURL), 100)
+        ])
+    } catch {
+        await fylo.rollback()
+    }
+})
+
+afterAll(async () => {
+    await Promise.all([Fylo.dropCollection(ALBUMS), Fylo.dropCollection(POSTS)])
+})
+
+describe("NO-SQL", async () => {
+
+    test("INNER JOIN — returns only join field values", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'inner',
+            $on: { userId: { $eq: 'userId' } }
+        }) as Record<`${_ttid}, ${_ttid}`, { userId: number }>
+
+        const pairs = Object.values(results)
+
+        expect(pairs.length).toBeGreaterThan(0)
+
+        // inner mode returns only the join fields, not full documents
+        for (const pair of pairs) {
+            expect(pair).toHaveProperty('userId')
+            expect(typeof pair.userId).toBe('number')
+        }
+    })
+
+    test("LEFT JOIN — returns full left-collection document", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'left',
+            $on: { userId: { $eq: 'userId' } }
+        }) as Record<`${_ttid}, ${_ttid}`, _album>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+
+        // left mode returns the full album (left collection) document
+        for (const doc of docs) {
+            expect(doc).toHaveProperty('title')
+            expect(doc).toHaveProperty('userId')
+        }
+    })
+
+    test("RIGHT JOIN — returns full right-collection document", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'right',
+            $on: { userId: { $eq: 'userId' } }
+        }) as Record<`${_ttid}, ${_ttid}`, _post>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+
+        // right mode returns the full post (right collection) document
+        for (const doc of docs) {
+            expect(doc).toHaveProperty('title')
+            expect(doc).toHaveProperty('body')
+            expect(doc).toHaveProperty('userId')
+        }
+    })
+
+    test("OUTER JOIN — returns merged left + right document", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'outer',
+            $on: { userId: { $eq: 'userId' } }
+        }) as Record<`${_ttid}, ${_ttid}`, _album & _post>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+
+        // outer mode merges both documents; both should have fields present
+        for (const doc of docs) {
+            expect(doc).toHaveProperty('userId')
+        }
+    })
+
+    test("JOIN with $limit — respects the result cap", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'inner',
+            $on: { userId: { $eq: 'userId' } },
+            $limit: 5
+        })
+
+        expect(Object.keys(results).length).toBe(5)
+    })
+
+    test("JOIN with $select — only requested fields are returned", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'left',
+            $on: { userId: { $eq: 'userId' } },
+            $select: ['title'],
+            $limit: 10
+        }) as Record<`${_ttid}, ${_ttid}`, Partial<_album>>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+
+        for (const doc of docs) {
+            expect(doc).toHaveProperty('title')
+            expect(doc).not.toHaveProperty('userId')
+        }
+    })
+
+    test("JOIN with $groupby — groups results by field value", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'inner',
+            $on: { userId: { $eq: 'userId' } },
+            $groupby: 'userId'
+        }) as Record<string, Record<string, unknown>>
+
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+
+    test("JOIN with $onlyIds — returns IDs only", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({
+            $leftCollection: ALBUMS,
+            $rightCollection: POSTS,
+            $mode: 'inner',
+            $on: { userId: { $eq: 'userId' } },
+            $onlyIds: true,
+            $limit: 10
+        }) as _ttid[]
+
+        expect(Array.isArray(results)).toBe(true)
+        expect(results.length).toBeGreaterThan(0)
+    })
+})
+
+describe("SQL", async () => {
+
+    test("INNER JOIN", async () => {
+
+        const results = await fylo.executeSQL<_album>(
+            `SELECT * FROM ${ALBUMS} INNER JOIN ${POSTS} ON userId = userId`
+        ) as Record<`${_ttid}, ${_ttid}`, _album | _post>
+
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+
+    test("LEFT JOIN", async () => {
+
+        const results = await fylo.executeSQL<_album>(
+            `SELECT * FROM ${ALBUMS} LEFT JOIN ${POSTS} ON userId = userId`
+        ) as Record<`${_ttid}, ${_ttid}`, _album>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+        expect(docs[0]).toHaveProperty('title')
+    })
+
+    test("RIGHT JOIN", async () => {
+
+        const results = await fylo.executeSQL<_post>(
+            `SELECT * FROM ${ALBUMS} RIGHT JOIN ${POSTS} ON userId = userId`
+        ) as Record<`${_ttid}, ${_ttid}`, _post>
+
+        const docs = Object.values(results)
+
+        expect(docs.length).toBeGreaterThan(0)
+        expect(docs[0]).toHaveProperty('body')
+    })
+})