@zveltio/sdk 3.0.0-beta.5 → 3.0.0-beta.70

package/dist/testing/with-test-db.js

@@ -24,15 +24,15 @@
  *     weight just to use `mockDb`. By importing lazily, the cost is
  *     opt-in at the call site.
  */
+import { parseMigrationSql } from '../validate/migration-parse.js';
 // ── Module-level reuse cache ────────────────────────────────────────────────
 //
 // When `reuse: true`, we keep a single container alive for the process
 // lifetime. The first call to `withTestDb` boots it; subsequent calls open
 // fresh DBs *inside* the same container (CREATE DATABASE per-call), so
 // tests stay isolated without paying the container-start cost again.
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
 let _sharedContainer = null;
-let _sharedClient = null;
-let _sharedDbCounter = 0;
 async function loadPgContainer() {
     try {
         return await import('@testcontainers/postgresql');
@@ -64,6 +64,7 @@ export async function startTestDb(opts = {}) {
     let port;
     let username;
     let password;
+    // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
     let createdContainer = null;
     if (opts.reuse && _sharedContainer) {
         host = _sharedContainer.getHost();
@@ -87,14 +88,15 @@ export async function startTestDb(opts = {}) {
     const adminPool = await openPgPool(adminConnStr);
     try {
         await adminPool.query(`CREATE DATABASE "${database}"`);
-        _sharedDbCounter++;
     }
     finally {
         await adminPool.end();
     }
     const connectionString = `postgres://${username}:${password}@${host}:${port}/${database}`;
     const pool = await openPgPool(connectionString);
+    // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
     const db = new Kysely({
+        // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
         dialect: new PostgresDialect({ pool: pool }),
     });
     if (opts.migrations && opts.migrations.length > 0) {
@@ -147,7 +149,11 @@ export async function startTestDb(opts = {}) {
  *     });
  *   });
  */
-export async function withTestDb(fnOrOpts, maybeFn) {
+export async function withTestDb(
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
+fnOrOpts, 
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
+maybeFn) {
     const opts = typeof fnOrOpts === 'function' ? {} : fnOrOpts;
     const fn = typeof fnOrOpts === 'function' ? fnOrOpts : maybeFn;
     if (typeof fn !== 'function') {
@@ -173,10 +179,17 @@ export async function withTestDb(fnOrOpts, maybeFn) {
  *   const files = glob('engine/migrations/*.sql').map((p) => readFileSync(p, 'utf8'));
  *   await applyMigrationStrings(db, files);
  */
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
 export async function applyMigrationStrings(db, sqlStrings) {
     const { sql } = await loadKysely();
     for (const raw of sqlStrings) {
-        const statements = splitStatements(raw);
+        // Only the UP half. A Zveltio migration keeps its rollback in the same file
+        // behind a `-- DOWN` marker, and the runner that applies it in production
+        // splits on that marker — this helper did not, so the documented example
+        // (glob `engine/migrations/*.sql`, hand them all to this function) created
+        // the schema and then dropped it again, in the same call. Every assertion
+        // after it failed on a table that had existed a statement earlier.
+        const statements = splitStatements(parseMigrationSql(raw).up);
         for (const stmt of statements) {
             const trimmed = stmt.trim();
             if (!trimmed)
@@ -189,6 +202,7 @@ export async function applyMigrationStrings(db, sqlStrings) {
  * Same as `applyMigrationStrings` but takes file paths. Reads each file
  * synchronously, applies in order. Bun-native — uses `Bun.file()`.
  */
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
 export async function applyMigrationFiles(db, paths) {
     // Bun.file().text() returns a Promise<string>.
     const contents = await Promise.all(paths.map((p) => Bun.file(p).text()));
@@ -200,15 +214,6 @@ export async function applyMigrationFiles(db, paths) {
  * reuse container is active.
  */
 export async function stopReusedTestDb() {
-    if (_sharedClient) {
-        try {
-            await _sharedClient.end();
-        }
-        catch {
-            /* */
-        }
-        _sharedClient = null;
-    }
     if (_sharedContainer) {
         try {
             await _sharedContainer.stop();
@@ -221,12 +226,14 @@ export async function stopReusedTestDb() {
 }
 // ── Internals ───────────────────────────────────────────────────────────────
 /** Open a pg connection pool. Uses `pg` (peer dep with testcontainers). */
+// biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
 async function openPgPool(connectionString) {
     const pg = await import('pg').catch(() => {
         throw new Error(`withTestDb requires the 'pg' npm package. Install it alongside testcontainers:\n` +
             `  bun add -d testcontainers pg @types/pg`);
     });
     // pg's Pool — the Kysely PostgresDialect accepts this directly.
+    // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
     return new pg.Pool({ connectionString });
 }
 /**

package/dist/tests/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/tests/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/tests/client.test.ts"],"names":[],"mappings":""}

package/dist/tests/client.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, afterEach } from 'bun:test';
+import { createZveltioClient } from '../client.js';
+const realFetch = globalThis.fetch;
+afterEach(() => {
+    globalThis.fetch = realFetch;
+});
+/** Records the URL each call is given and answers `{}` without a network hop. */
+function captureUrls() {
+    const urls = [];
+    globalThis.fetch = (async (input) => {
+        urls.push(String(input));
+        return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+    });
+    return urls;
+}
+describe('ZveltioClient URL building', () => {
+    it('encodes a record id into a single path segment', async () => {
+        const urls = captureUrls();
+        const client = createZveltioClient({ baseUrl: 'https://engine.test' });
+        const products = client.collection('products');
+        await products.get('a/b');
+        await products.update('a/b', { name: 'x' });
+        await products.delete('a/b');
+        expect(urls).toEqual([
+            'https://engine.test/api/data/products/a%2Fb',
+            'https://engine.test/api/data/products/a%2Fb',
+            'https://engine.test/api/data/products/a%2Fb',
+        ]);
+    });
+    it('asks the engine who its key is at the route that answers it', async () => {
+        const urls = captureUrls();
+        const client = createZveltioClient({ baseUrl: 'https://engine.test', apiKey: 'zvk_x' });
+        await client.auth.apiKey();
+        expect(urls).toEqual(['https://engine.test/api/api-keys/self']);
+    });
+    it('encodes the storage folder into the query string', async () => {
+        const urls = captureUrls();
+        const client = createZveltioClient({ baseUrl: 'https://engine.test' });
+        await client.storage.list('invoices&limit=9999');
+        expect(urls).toEqual(['https://engine.test/api/storage?folder_id=invoices%26limit%3D9999']);
+    });
+    it('sends the upload folder under the field name the engine reads', async () => {
+        let body;
+        globalThis.fetch = (async (_input, init) => {
+            body = init?.body;
+            return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+        });
+        const client = createZveltioClient({ baseUrl: 'https://engine.test' });
+        await client.storage.upload(new File(['x'], 'a.txt'), 'folder-uuid');
+        expect(body?.get('folder_id')).toBe('folder-uuid');
+        expect(body?.has('folder')).toBe(false);
+    });
+    it('leaves an ordinary id and collection name untouched', async () => {
+        const urls = captureUrls();
+        const client = createZveltioClient({ baseUrl: 'https://engine.test/' });
+        await client.collection('order_items').get('018f2a1e-0000-7000-8000-000000000000');
+        expect(urls).toEqual([
+            'https://engine.test/api/data/order_items/018f2a1e-0000-7000-8000-000000000000',
+        ]);
+    });
+});

package/dist/tests/crdt-orset.test.d.ts

@@ -0,0 +1,2 @@
+import './setup';
+//# sourceMappingURL=crdt-orset.test.d.ts.map

package/dist/tests/crdt-orset.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-orset.test.d.ts","sourceRoot":"","sources":["../../src/tests/crdt-orset.test.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,CAAC"}

package/dist/tests/crdt-orset.test.js

@@ -0,0 +1,23 @@
+import './setup';
+import { describe, it, expect } from 'bun:test';
+import { orSetAdd, orSetRemove, orSetMerge, orSetValues } from '../crdt.js';
+describe('OR-Set — removal survives a merge with a stale replica', () => {
+    it('does not resurrect an element that one replica removed', () => {
+        const added = orSetAdd([], 'x');
+        const uid = added[0].uid;
+        const stale = [...added]; // a replica that never saw the removal
+        const removed = orSetRemove(added, uid);
+        const first = orSetMerge(removed, stale);
+        expect(orSetValues(first)).toEqual([]);
+        // The stale replica syncs again. Without its tombstone the merged set has
+        // no record of the removal, so the element reads as a fresh addition.
+        const second = orSetMerge(first, stale);
+        expect(orSetValues(second), 'the removed element came back').toEqual([]);
+    });
+    it('an element added after a removal is kept', () => {
+        const first = orSetAdd([], 'x');
+        const removed = orSetRemove(first, first[0].uid);
+        const readded = orSetAdd(removed, 'x');
+        expect(orSetValues(orSetMerge(readded, removed))).toEqual(['x']);
+    });
+});

package/dist/tests/local-store.test.js

@@ -74,3 +74,47 @@ describe('LocalStore — conflict detection', () => {
         expect(rec?._conflictData).toBeUndefined();
     });
 });
+describe('LocalStore — what the SyncManager actually passes', () => {
+    let store;
+    beforeEach(async () => {
+        store = new LocalStore();
+        await store.open();
+        await store.clear();
+    });
+    afterEach(async () => {
+        await store.close();
+    });
+    it('flags a conflict when the confirmed server version is an epoch timestamp', async () => {
+        // `syncNow()` and `pull()` both pass `Date.now()` as the server version —
+        // the collections API returns no version column. From the first ACK on,
+        // `_serverVersion` is ~1.79e12 and `_localVersion` is still a small counter,
+        // so the version comparison alone can never be true again and every local
+        // edit was overwritten in silence.
+        await store.put('posts', 'rec-ts', { title: 'v1' });
+        const [op] = await store.getPendingOps();
+        await store.markSynced(op.id, 'posts', 'rec-ts', Date.now());
+        await store.put('posts', 'rec-ts', { title: 'local edit' });
+        await store.applyServerUpdate('posts', 'rec-ts', { title: 'server wins' }, Date.now());
+        const after = await store.get('posts', 'rec-ts');
+        expect(after?._syncStatus).toBe('conflict');
+        expect(after?.data).toEqual({ title: 'local edit' });
+        expect(after?._conflictData).toEqual({ title: 'server wins' });
+    });
+    it('queues the resolved row, so a resolution reaches the server', async () => {
+        await store.applyServerUpdate('posts', 'rec-res', { title: 'server' }, Date.now());
+        await store.resolveConflict('posts', 'rec-res', { title: 'resolved' });
+        const ops = await store.getPendingOps();
+        const mine = ops.filter((o) => o.recordId === 'rec-res');
+        expect(mine, 'the resolution was never queued').toHaveLength(1);
+        expect(mine[0].payload).toEqual({ title: 'resolved' });
+        expect(mine[0].operation).toBe('update');
+    });
+    it('keeps the CRDT document across a clean server update', async () => {
+        await store.put('posts', 'rec-crdt', { title: 'local' });
+        const [op] = await store.getPendingOps();
+        await store.markSynced(op.id, 'posts', 'rec-crdt', Date.now());
+        await store.applyServerUpdate('posts', 'rec-crdt', { title: 'server' }, Date.now());
+        const after = await store.get('posts', 'rec-crdt');
+        expect(after?._crdtDoc, 'the CRDT document was dropped, so no later merge can run').toBeDefined();
+    });
+});

package/dist/tests/multipart.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=multipart.test.d.ts.map

package/dist/tests/multipart.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.test.d.ts","sourceRoot":"","sources":["../../src/tests/multipart.test.ts"],"names":[],"mappings":""}

package/dist/tests/multipart.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'bun:test';
+import { MULTIPART_REQUIRED, readMultipart } from '../extension/multipart.js';
+/**
+ * Six upload handlers opened with a bare `await c.req.formData()` and put their
+ * "no file provided" 400 on the line after it. `formData()` throws when the body
+ * is not multipart, so that 400 was unreachable for exactly the requests it was
+ * written for, and they came back as a bare 500 instead.
+ *
+ * Both directions are asserted here. A guard that rejects everything would also
+ * make the suite green, and would break every upload in the product.
+ */
+const ctxWith = (body, headers = {}) => {
+    const req = new Request('http://x/upload', { method: 'POST', body, headers });
+    return { req: { formData: () => req.formData() } };
+};
+describe('readMultipart', () => {
+    it('parses a real multipart body, fields and files alike', async () => {
+        const fd = new FormData();
+        fd.append('file', new File(['salut'], 'a.txt', { type: 'text/plain' }));
+        fd.append('path', '/docs');
+        const form = await readMultipart(ctxWith(fd));
+        expect(form).not.toBeNull();
+        expect(form?.get('file')?.name).toBe('a.txt');
+        expect(form?.get('path')).toBe('/docs');
+    });
+    it('answers null for every body shape that used to throw', async () => {
+        expect(await readMultipart(ctxWith('{}', { 'content-type': 'application/json' }))).toBeNull();
+        expect(await readMultipart(ctxWith(null))).toBeNull();
+        expect(await readMultipart(ctxWith('salut', { 'content-type': 'text/plain' }))).toBeNull();
+    });
+    it('does not leak the parser own message to the caller', async () => {
+        // The body parser's error reads like "FormData parse error" — nothing a
+        // caller can act on, and echoing a parser's internals over HTTP is how
+        // request contents end up in error strings.
+        expect(MULTIPART_REQUIRED).toEqual({ error: 'Expected a multipart/form-data body.' });
+    });
+});

package/dist/tests/offline-provider-crdt.test.d.ts

@@ -0,0 +1,2 @@
+import './setup';
+//# sourceMappingURL=offline-provider-crdt.test.d.ts.map

package/dist/tests/offline-provider-crdt.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-provider-crdt.test.d.ts","sourceRoot":"","sources":["../../src/tests/offline-provider-crdt.test.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,CAAC"}

package/dist/tests/offline-provider-crdt.test.js

@@ -0,0 +1,119 @@
+import './setup';
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { LocalStore } from '../local-store.js';
+import { createOfflineProvider } from '../offline/index.js';
+/**
+ * The CRDT provider is the DEFAULT (`config.provider ?? 'crdt'`) and it did
+ * nothing at all: `pull()` was an empty body, `subscribe()` returned an
+ * unsubscribe for nothing, and `push()` returned `0` — which reads as "there
+ * was nothing to send" rather than "I did not look". An application that called
+ * `createOfflineProvider({ engineUrl })` and pushed on a timer got a clean run
+ * and an empty server, forever, with nothing in any log.
+ *
+ * The test that existed asserted exactly that: `await expect(p.push())
+ * .resolves.toBe(0)`, under the title "builds a working stub". It passed for the
+ * whole life of the defect.
+ *
+ * So these assert the crossing — what ends up in the local store, and what the
+ * count means — rather than that the methods are callable.
+ */
+const ENGINE = 'http://engine.test';
+/** Rows the fake engine holds, by collection. */
+let served = {};
+/** Every request the provider made, so "did it even ask" is answerable. */
+let requests = [];
+const realFetch = globalThis.fetch;
+beforeEach(async () => {
+    served = {};
+    requests = [];
+    globalThis.fetch = (async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        requests.push(`${init?.method ?? 'GET'} ${url.replace(ENGINE, '')}`);
+        const match = url.match(/\/api\/data\/([^/?]+)/);
+        const name = match?.[1] ?? '';
+        const page = Number(new URL(url).searchParams.get('page') ?? '1');
+        // One page only: page 2 comes back empty, which is how `pull` stops.
+        const data = page === 1 ? (served[name] ?? []) : [];
+        return new Response(JSON.stringify({ data, total: data.length, page, limit: 200 }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        });
+    });
+    const store = new LocalStore();
+    await store.open();
+    await store.clear();
+    await store.close();
+});
+afterEach(() => {
+    globalThis.fetch = realFetch;
+});
+async function localRows(collection) {
+    const store = new LocalStore();
+    await store.open();
+    const rows = await store.list(collection);
+    await store.close();
+    return rows;
+}
+describe('createOfflineProvider — the crdt path actually syncs', () => {
+    it('is the default provider, which is why the no-op mattered', async () => {
+        const p = await createOfflineProvider({ engineUrl: ENGINE });
+        expect(p.kind).toBe('crdt');
+        await p.close();
+    });
+    it('pull writes the server rows into the local store', async () => {
+        served.orders = [
+            { id: 'o-1', total: 10, status: 'new' },
+            { id: 'o-2', total: 20, status: 'paid' },
+        ];
+        const p = await createOfflineProvider({ engineUrl: ENGINE, tables: ['orders'] });
+        await p.pull();
+        await p.close();
+        const rows = await localRows('orders');
+        expect(rows.map((r) => r.id).sort()).toEqual(['o-1', 'o-2']);
+        expect(rows.find((r) => r.id === 'o-1')?.data.total).toBe(10);
+        // The old implementation made no request at all. This is the assertion that
+        // would have caught it.
+        expect(requests.some((r) => r.startsWith('GET /api/data/orders'))).toBe(true);
+    });
+    it('pull refuses an empty table list instead of quietly doing nothing', async () => {
+        // Silence here is exactly what the no-op was. A provider asked to replicate
+        // nothing is a configuration mistake, and an empty local database looks the
+        // same as an empty server.
+        const p = await createOfflineProvider({ engineUrl: ENGINE });
+        await expect(p.pull()).rejects.toThrow(/tables.*is empty/i);
+        await p.close();
+    });
+    it('push reports how many queued operations it actually sent', async () => {
+        const p = await createOfflineProvider({ engineUrl: ENGINE, tables: ['orders'] });
+        // Queue two local writes the way an offline application does.
+        const store = new LocalStore();
+        await store.open();
+        await store.put('orders', 'o-9', { total: 99 });
+        await store.put('orders', 'o-10', { total: 100 });
+        const queued = await store.getPendingOps();
+        await store.close();
+        expect(queued.length).toBe(2);
+        const sent = await p.push();
+        await p.close();
+        expect(sent).toBe(2);
+        // Not just a number: the writes have to have left the machine.
+        expect(requests.filter((r) => r.startsWith('POST /api/data/orders')).length).toBe(2);
+    });
+    it('subscribe delivers the local rows, and the unsubscribe stops delivery', async () => {
+        served.orders = [{ id: 'o-1', total: 10 }];
+        const p = await createOfflineProvider({ engineUrl: ENGINE, tables: ['orders'] });
+        await p.pull();
+        const seen = [];
+        const off = p.subscribe('orders', (rows) => seen.push(rows));
+        await Bun.sleep(20);
+        expect(seen.length).toBeGreaterThan(0);
+        expect(seen.at(-1).map((r) => r.id)).toEqual(['o-1']);
+        off();
+        const countAtUnsubscribe = seen.length;
+        // A second pull notifies listeners; an unsubscribed callback must not hear it.
+        await p.pull();
+        await Bun.sleep(20);
+        expect(seen.length).toBe(countAtUnsubscribe);
+        await p.close();
+    });
+});

package/dist/tests/realtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=realtime.test.d.ts.map

package/dist/tests/realtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.test.d.ts","sourceRoot":"","sources":["../../src/tests/realtime.test.ts"],"names":[],"mappings":""}