@delma/fylo 1.0.0

package/tests/integration/nested.test.ts

@@ -0,0 +1,212 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import { usersURL } from '../data'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+/**
+ * _user has deeply nested fields:
+ *   address.street, address.suite, address.city, address.zipcode
+ *   address.geo.lat, address.geo.lng
+ *   company.name, company.catchPhrase, company.bs
+ *
+ * This exercises the recursive branch in Dir.extractKeys and the nested
+ * path reconstruction in Dir.constructData.
+ */
+
+const USERS = 'nst-user'
+
+let insertedCount = 0
+let sampleId: _ttid
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(USERS)
+    try {
+        insertedCount = await fylo.importBulkData<_user>(USERS, new URL(usersURL))
+    } catch {
+        await fylo.rollback()
+    }
+
+    for await (const data of Fylo.findDocs<_user>(USERS, { $limit: 1, $onlyIds: true }).collect()) {
+        sampleId = data as _ttid
+    }
+})
+
+afterAll(async () => {
+    await Fylo.dropCollection(USERS)
+})
+
+describe("NO-SQL", async () => {
+
+    test("SELECT ALL — nested documents are returned", async () => {
+
+        let results: Record<_ttid, _user> = {}
+
+        for await (const data of Fylo.findDocs<_user>(USERS).collect()) {
+            results = { ...results, ...data as Record<_ttid, _user> }
+        }
+
+        expect(Object.keys(results).length).toBe(insertedCount)
+    })
+
+    test("GET ONE — top-level fields are reconstructed correctly", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const user = result[sampleId]
+
+        expect(user).toBeDefined()
+        expect(typeof user.name).toBe('string')
+        expect(typeof user.email).toBe('string')
+        expect(typeof user.phone).toBe('string')
+    })
+
+    test("GET ONE — first-level nested object is reconstructed correctly", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const user = result[sampleId]
+
+        expect(user.address).toBeDefined()
+        expect(typeof user.address.city).toBe('string')
+        expect(typeof user.address.street).toBe('string')
+        expect(typeof user.address.zipcode).toBe('string')
+    })
+
+    test("GET ONE — deeply nested object is reconstructed correctly", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const user = result[sampleId]
+
+        expect(user.address.geo).toBeDefined()
+        expect(typeof user.address.geo.lat).toBe('number')
+        expect(typeof user.address.geo.lng).toBe('number')
+    })
+
+    test("GET ONE — second nested object is reconstructed correctly", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const user = result[sampleId]
+
+        expect(user.company).toBeDefined()
+        expect(typeof user.company.name).toBe('string')
+        expect(typeof user.company.catchPhrase).toBe('string')
+        expect(typeof user.company.bs).toBe('string')
+    })
+
+    test("SELECT — nested values are not corrupted across documents", async () => {
+
+        for await (const data of Fylo.findDocs<_user>(USERS).collect()) {
+
+            const [, user] = Object.entries(data as Record<_ttid, _user>)[0]
+
+            expect(user.address).toBeDefined()
+            expect(user.address.geo).toBeDefined()
+            expect(typeof user.address.geo.lat).toBe('number')
+            expect(user.company).toBeDefined()
+        }
+    })
+
+    test("$select — returns only requested top-level fields", async () => {
+
+        let results: Record<_ttid, _user> = {}
+
+        for await (const data of Fylo.findDocs<_user>(USERS, { $select: ['name', 'email'] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _user> }
+        }
+
+        const users = Object.values(results)
+        const onlyNameAndEmail = users.every(u => u.name && u.email && !u.phone && !u.address)
+
+        expect(onlyNameAndEmail).toBe(true)
+    })
+
+    test("$eq on nested string field — query by city", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const targetCity = result[sampleId].address.city
+
+        let results: Record<_ttid, _user> = {}
+
+        for await (const data of Fylo.findDocs<_user>(USERS, {
+            $ops: [{ ['address/city' as keyof _user]: { $eq: targetCity } }]
+        }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _user> }
+        }
+
+        const matchingUsers = Object.values(results)
+        const allMatch = matchingUsers.every(u => u.address.city === targetCity)
+
+        expect(allMatch).toBe(true)
+        expect(matchingUsers.length).toBeGreaterThan(0)
+    })
+})
+
+describe("SQL — dot notation", async () => {
+
+    test("WHERE with dot notation — first-level nested field", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const targetCity = result[sampleId].address.city
+
+        const results = await fylo.executeSQL<_user>(
+            `SELECT * FROM ${USERS} WHERE address.city = '${targetCity}'`
+        ) as Record<_ttid, _user>
+
+        const users = Object.values(results)
+        const allMatch = users.every(u => u.address.city === targetCity)
+
+        expect(allMatch).toBe(true)
+        expect(users.length).toBeGreaterThan(0)
+    })
+
+    test("WHERE with dot notation — deeply nested field", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const targetLat = result[sampleId].address.geo.lat
+
+        const results = await fylo.executeSQL<_user>(
+            `SELECT * FROM ${USERS} WHERE address.geo.lat = '${targetLat}'`
+        ) as Record<_ttid, _user>
+
+        const users = Object.values(results)
+        const allMatch = users.every(u => u.address.geo.lat === targetLat)
+
+        expect(allMatch).toBe(true)
+        expect(users.length).toBeGreaterThan(0)
+    })
+
+    test("WHERE with dot notation — second nested object", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const targetCompany = result[sampleId].company.name
+
+        const results = await fylo.executeSQL<_user>(
+            `SELECT * FROM ${USERS} WHERE company.name = '${targetCompany}'`
+        ) as Record<_ttid, _user>
+
+        const users = Object.values(results)
+        const allMatch = users.every(u => u.company.name === targetCompany)
+
+        expect(allMatch).toBe(true)
+        expect(users.length).toBeGreaterThan(0)
+    })
+
+    test("SELECT with dot notation in WHERE — partial field selection", async () => {
+
+        const result = await Fylo.getDoc<_user>(USERS, sampleId).once()
+        const targetCity = result[sampleId].address.city
+
+        const results = await fylo.executeSQL<_user>(
+            `SELECT name, email FROM ${USERS} WHERE address.city = '${targetCity}'`
+        ) as Record<_ttid, _user>
+
+        const users = Object.values(results)
+
+        expect(users.length).toBeGreaterThan(0)
+        expect(users.every(u => u.name && u.email && !u.phone)).toBe(true)
+    })
+})

package/tests/integration/operators.test.ts

@@ -0,0 +1,167 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import { albumURL } from '../data'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+/**
+ * Albums from JSONPlaceholder: 100 records, userId 1–10, 10 albums per userId.
+ *
+ * NOTE: The numeric-range glob generator in query.ts produces digit-by-digit
+ * character classes (e.g. $gt:5 → "[6-9]"). This correctly matches single-digit
+ * values but misses two-digit values like 10. Tests below assert correct expected
+ * values so any regression in the generator is surfaced immediately.
+ */
+
+const ALBUMS = 'ops-album'
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(ALBUMS)
+    try {
+        await fylo.importBulkData<_album>(ALBUMS, new URL(albumURL), 100)
+    } catch {
+        await fylo.rollback()
+    }
+})
+
+afterAll(async () => {
+    await Fylo.dropCollection(ALBUMS)
+})
+
+describe("NO-SQL", async () => {
+
+    test("$ne — excludes matching value", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $ne: 1 } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const hasUserId1 = albums.some(a => a.userId === 1)
+
+        expect(hasUserId1).toBe(false)
+        expect(albums.length).toBe(90)
+    })
+
+    test("$lt — returns documents where field is less than value", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $lt: 5 } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allLessThan5 = albums.every(a => a.userId < 5)
+
+        expect(allLessThan5).toBe(true)
+        expect(albums.length).toBe(40) // userId 1,2,3,4 → 4×10
+    })
+
+    test("$lte — returns documents where field is less than or equal to value", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $lte: 5 } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allLte5 = albums.every(a => a.userId <= 5)
+
+        expect(allLte5).toBe(true)
+        expect(albums.length).toBe(50) // userId 1,2,3,4,5 → 5×10
+    })
+
+    test("$gt — returns documents where field is greater than value", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $gt: 5 } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allGt5 = albums.every(a => a.userId > 5)
+
+        expect(allGt5).toBe(true)
+        expect(albums.length).toBe(50) // userId 6,7,8,9,10 → 5×10
+    })
+
+    test("$gte — returns documents where field is greater than or equal to value", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $gte: 5 } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allGte5 = albums.every(a => a.userId >= 5)
+
+        expect(allGte5).toBe(true)
+        expect(albums.length).toBe(60) // userId 5,6,7,8,9,10 → 6×10
+    })
+
+    test("$like — matches substring pattern", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ title: { $like: '%quidem%' } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allMatch = albums.every(a => a.title.includes('quidem'))
+
+        expect(allMatch).toBe(true)
+        expect(albums.length).toBeGreaterThan(0)
+    })
+
+    test("$like — prefix pattern", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ title: { $like: 'omnis%' } }] }).collect()) {
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        const albums = Object.values(results)
+        const allStartWith = albums.every(a => a.title.startsWith('omnis'))
+
+        expect(allStartWith).toBe(true)
+        expect(albums.length).toBeGreaterThan(0)
+    })
+})
+
+describe("SQL", async () => {
+
+    test("WHERE != — excludes matching value", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} WHERE userId != 1`) as Record<_ttid, _album>
+
+        const albums = Object.values(results)
+        const hasUserId1 = albums.some(a => a.userId === 1)
+
+        expect(hasUserId1).toBe(false)
+        expect(albums.length).toBe(90)
+    })
+
+    test("WHERE LIKE — matches substring pattern", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} WHERE title LIKE '%quidem%'`) as Record<_ttid, _album>
+
+        const albums = Object.values(results)
+        const allMatch = albums.every(a => a.title.includes('quidem'))
+
+        expect(allMatch).toBe(true)
+        expect(albums.length).toBeGreaterThan(0)
+    })
+})

package/tests/integration/read.test.ts

@@ -0,0 +1,203 @@
+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'
+
+const POSTS = `post`
+const ALBUMS = `album`
+
+let count = 0
+
+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.executeSQL<_post>(`CREATE TABLE ${POSTS}`)])
+
+    try {
+        count = await fylo.importBulkData<_album>(ALBUMS, new URL(albumURL), 100)
+        await 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("SELECT ALL", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS).collect()) { 
+
+            results = { ...results, ... data as Record<_ttid, _album> }
+        }
+
+        //console.format(results)
+
+        expect(Object.keys(results).length).toBe(count)
+    })
+
+    test("SELECT PARTIAL", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $select: ["title"] }).collect()) {
+
+            results = { ...results, ... data as Record<_ttid, _album> }
+        }
+
+        //console.format(results)
+        
+        const allAlbums = Object.values(results)
+
+        const onlyTtitle = allAlbums.every(user => user.title && !user.userId)
+
+        expect(onlyTtitle).toBe(true)
+
+    })
+
+    test("GET ONE", async () => {
+
+        const ids: _ttid[] = []
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $limit: 1, $onlyIds: true }).collect()) {
+
+            ids.push(data as _ttid)
+        }
+
+        const result = await Fylo.getDoc<_album>(ALBUMS, ids[0]).once()
+        
+        const _id = Object.keys(result).shift()!
+
+        expect(ids[0]).toEqual(_id)
+    })
+
+    test("SELECT CLAUSE", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $ops: [{ userId: { $eq: 2 } }] }).collect()) {
+
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        //console.format(results)
+
+        const allAlbums = Object.values(results)
+        
+        const onlyUserId = allAlbums.every(user => user.userId === 2)
+
+        expect(onlyUserId).toBe(true)
+    })
+
+    test("SELECT LIMIT", async () => {
+
+        let results: Record<_ttid, _album> = {}
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $limit: 5 }).collect()) {
+
+            results = { ...results, ...data as Record<_ttid, _album> }
+        }
+
+        //console.format(results)
+
+        expect(Object.keys(results).length).toBe(5)
+    })
+
+    test("SELECT GROUP BY", async () => {
+
+        let results: Record<_album[keyof _album], Record<_ttid, Partial<_album>>> = {} as Record<_album[keyof _album], Record<_ttid, Partial<_album>>>
+
+        for await (const data of Fylo.findDocs<_album>(ALBUMS, { $groupby: "userId", $onlyIds: true }).collect()) {
+            
+            results = Object.appendGroup(results, (data as unknown as Record<string, Record<string, Record<_ttid, null>>>)) 
+        }
+
+        //console.format(results)
+
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+
+    test("SELECT JOIN", async () => {
+
+        const results = await Fylo.joinDocs<_album, _post>({ $leftCollection: ALBUMS, $rightCollection: POSTS, $mode: "inner",  $on: { "userId": { $eq: "id" } } }) as Record<`${_ttid}, ${_ttid}`, _album | _post>
+        
+        //console.format(results)
+        
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+})
+
+describe("SQL", async () => {
+
+    test("SELECT PARTIAL", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT title FROM ${ALBUMS}`) as Record<_ttid, _album>
+        
+        //console.format(results)
+        
+        const allAlbums = Object.values(results)
+        
+        const onlyTtitle = allAlbums.every(user => user.title && !user.userId)
+
+        expect(onlyTtitle).toBe(true)
+    })
+
+    test("SELECT CLAUSE", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} WHERE user_id = 2`) as Record<_ttid, _album>
+        
+        //console.format(results)
+        
+        const allAlbums = Object.values(results)
+        
+        const onlyUserId = allAlbums.every(user => user.userId === 2)
+
+        expect(onlyUserId).toBe(true)
+    })
+
+    test("SELECT ALL", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS}`) as Record<_ttid, _album>
+        
+        //console.format(results)
+        
+        expect(Object.keys(results).length).toBe(count)
+    })
+
+    test("SELECT LIMIT", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} LIMIT 5`) as Record<_ttid, _album>
+        
+        //console.format(results)
+        
+        expect(Object.keys(results).length).toBe(5)
+    })
+
+    test("SELECT GROUP BY", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} GROUP BY userId`) as unknown as Record<string, Record<keyof _album, Record<_album[keyof _album], _album>>>
+        
+        //console.format(results)
+        
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+
+    test("SELECT JOIN", async () => {
+
+        const results = await fylo.executeSQL<_album>(`SELECT * FROM ${ALBUMS} INNER JOIN ${POSTS} ON userId = id`) as Record<`${_ttid}, ${_ttid}`, _album | _post>
+        
+        //console.format(results)
+        
+        expect(Object.keys(results).length).toBeGreaterThan(0)
+    })
+})

package/tests/integration/rollback.test.ts

@@ -0,0 +1,105 @@
+import { test, expect, describe, beforeAll, afterAll, mock } from 'bun:test'
+import Fylo from '../../src'
+import S3Mock from '../mocks/s3'
+import RedisMock from '../mocks/redis'
+
+/**
+ * Rollback mechanism:
+ *   - putKeys() pushes S3.delete ops into the transactions stack
+ *   - deleteKeys() pushes S3.put ops (restore) into the stack
+ *   - executeRollback() pops and executes them in reverse order
+ *
+ * After rollback, the written data should no longer be retrievable.
+ * After a delete rollback, the deleted data should be restored.
+ */
+
+const POSTS = 'rb-post'
+
+const fylo = new Fylo()
+
+mock.module('../../src/adapters/s3', () => ({ S3: S3Mock }))
+mock.module('../../src/adapters/redis', () => ({ Redis: RedisMock }))
+
+beforeAll(async () => {
+    await Fylo.createCollection(POSTS)
+})
+
+afterAll(async () => {
+    await Fylo.dropCollection(POSTS)
+})
+
+describe("NO-SQL", () => {
+
+    test("INSERT then rollback — document is not retrievable", async () => {
+
+        const _id = await fylo.putData<_post>(POSTS, {
+            userId: 99,
+            id: 9001,
+            title: 'Rollback Me',
+            body: 'This document should disappear after rollback'
+        })
+
+        // Verify the document was actually written
+        const before = await Fylo.getDoc<_post>(POSTS, _id).once()
+        expect(Object.keys(before).length).toBe(1)
+
+        // Rollback undoes all writes made on this Fylo instance
+        await fylo.rollback()
+
+        const after = await Fylo.getDoc<_post>(POSTS, _id).once()
+        expect(Object.keys(after).length).toBe(0)
+    })
+
+    test("DELETE then rollback — document is restored", async () => {
+
+        // Use a fresh Fylo instance so the transactions stack is clean
+        const freshFylo = new Fylo()
+
+        const _id = await freshFylo.putData<_post>(POSTS, {
+            userId: 99,
+            id: 9002,
+            title: 'Restore Me',
+            body: 'This document should reappear after delete rollback'
+        })
+
+        // Clear the insert transactions so rollback only covers the delete
+        // (call rollback would delete the just-written doc, defeating the purpose)
+        // Instead we use a second instance that has a clean transaction stack
+        const deleteInstance = new Fylo()
+
+        await deleteInstance.delDoc(POSTS, _id)
+
+        // Confirm it's gone
+        const after = await Fylo.getDoc<_post>(POSTS, _id).once()
+        expect(Object.keys(after).length).toBe(0)
+
+        // Rollback the delete — should restore the document
+        await deleteInstance.rollback()
+
+        const restored = await Fylo.getDoc<_post>(POSTS, _id).once()
+        expect(Object.keys(restored).length).toBe(1)
+        expect(restored[_id].title).toBe('Restore Me')
+    })
+
+    test("batch INSERT then rollback — all documents are removed", async () => {
+
+        const batchFylo = new Fylo()
+
+        const batch: _post[] = [
+            { userId: 98, id: 9003, title: 'Batch A', body: 'body a' },
+            { userId: 98, id: 9004, title: 'Batch B', body: 'body b' },
+            { userId: 98, id: 9005, title: 'Batch C', body: 'body c' }
+        ]
+
+        const ids = await batchFylo.batchPutData<_post>(POSTS, batch)
+
+        // Confirm all written
+        const beforeResults = await Promise.all(ids.map(id => Fylo.getDoc<_post>(POSTS, id).once()))
+        expect(beforeResults.every(r => Object.keys(r).length === 1)).toBe(true)
+
+        await batchFylo.rollback()
+
+        const afterResults = await Promise.all(ids.map(id => Fylo.getDoc<_post>(POSTS, id).once()))
+        expect(afterResults.every(r => Object.keys(r).length === 0)).toBe(true)
+    })
+})