@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/sqlite/transactions.ts

@@ -1,33 +1,33 @@
-/**
- * The transaction primitive.
- *
- * A transaction never spans two scopes, and not because a check forbids it:
- * a transaction runs on one connection, a connection is opened against one
- * scope's file, and the public surface offers no way to reach a second one
- * from inside. FR-038 is a type error rather than a runtime one (research.md
- * R2).
- *
- * Rollback fidelity is SQLite's, not this package's. A failure at any step
- * unwinds through the engine's own `ROLLBACK`, which is the only way SC-006's
- * "identical to its pre-transaction state, every time" survives a process
- * kill halfway through.
- */
-
-import type { Connection, TransactionExecutor } from './connection';
-
-/**
- * Run `body` inside one transaction on one scope.
- *
- * Deliberately thin. The interesting behavior — read-your-own-writes,
- * terminal-state rejection, what a settled transaction does when used again —
- * belongs to `adapter/transaction.ts`, where both adapters can be held to the
- * same rules.
- */
-export function runInTransaction<R>(
-	connection: Connection,
-	body: (tx: TransactionExecutor) => Promise<R>,
-): Promise<R> {
-	return connection.transaction(body);
-}
-
-export type { TransactionExecutor };
+/**
+ * The transaction primitive.
+ *
+ * A transaction never spans two scopes, and not because a check forbids it:
+ * a transaction runs on one connection, a connection is opened against one
+ * scope's file, and the public surface offers no way to reach a second one
+ * from inside. FR-038 is a type error rather than a runtime one (research.md
+ * R2).
+ *
+ * Rollback fidelity is SQLite's, not this package's. A failure at any step
+ * unwinds through the engine's own `ROLLBACK`, which is the only way SC-006's
+ * "identical to its pre-transaction state, every time" survives a process
+ * kill halfway through.
+ */
+
+import type { Connection, TransactionExecutor } from './connection';
+
+/**
+ * Run `body` inside one transaction on one scope.
+ *
+ * Deliberately thin. The interesting behavior — read-your-own-writes,
+ * terminal-state rejection, what a settled transaction does when used again —
+ * belongs to `adapter/transaction.ts`, where both adapters can be held to the
+ * same rules.
+ */
+export function runInTransaction<R>(
+	connection: Connection,
+	body: (tx: TransactionExecutor) => Promise<R>,
+): Promise<R> {
+	return connection.transaction(body);
+}
+
+export type { TransactionExecutor };

package/src/sqlite/values.ts

@@ -1,24 +1,24 @@
-/**
- * Reading values back out of a result row.
- *
- * The engine hands back `unknown` per column, and every read site would
- * otherwise repeat the same `String(...)` / `Number(...)` coercion with a
- * slightly different null check. One place to do it means one place where the
- * "NULL means absent, not empty string" rule is decided.
- */
-
-export function text(value: unknown): string {
-	return typeof value === 'string' ? value : String(value as string | number | boolean);
-}
-
-export function num(value: unknown): number {
-	return typeof value === 'number' ? value : Number(value as string | number);
-}
-
-export function maybeText(value: unknown): string | null {
-	return value == null ? null : text(value);
-}
-
-export function maybeNum(value: unknown): number | null {
-	return value == null ? null : num(value);
-}
+/**
+ * Reading values back out of a result row.
+ *
+ * The engine hands back `unknown` per column, and every read site would
+ * otherwise repeat the same `String(...)` / `Number(...)` coercion with a
+ * slightly different null check. One place to do it means one place where the
+ * "NULL means absent, not empty string" rule is decided.
+ */
+
+export function text(value: unknown): string {
+	return typeof value === 'string' ? value : String(value as string | number | boolean);
+}
+
+export function num(value: unknown): number {
+	return typeof value === 'number' ? value : Number(value as string | number);
+}
+
+export function maybeText(value: unknown): string | null {
+	return value == null ? null : text(value);
+}
+
+export function maybeNum(value: unknown): number | null {
+	return value == null ? null : num(value);
+}

package/src/testing/conformance/attachments.ts

@@ -1,136 +1,139 @@
-import { DiagnosticCodes } from '../../contract/errors';
-import { isCode } from '../../diagnostics/errors';
-import type { ConformanceContext } from './index';
-
-/** US7: artifacts the package owns, and the reconciliation that keeps them honest. */
-export function registerAttachmentConformance(context: ConformanceContext): void {
-	describe('conformance: attachments', () => {
-		beforeEach(() => context.reset());
-
-		const scope = { kind: 'guest' } as const;
-		const content = Buffer.from('hello attachment', 'utf8').toString('base64');
-
-		it('stores a reference alongside the artifact', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			const attachments = handle.attachments();
-			const reference = await attachments.write({
-				id: 'a1',
-				owner: { collection: 'notes', id: 'n1' },
-				contentType: 'text/plain',
-				content,
-			});
-
-			expect(reference.size).toBe(Buffer.from(content, 'base64').length);
-			expect(await attachments.read('a1')).toBe(content);
-			expect((await attachments.availability('a1')).state).toBe('available');
-			await handle.close();
-		});
-
-		it('reads a byte range without materialising the whole artifact', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			const attachments = handle.attachments();
-			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
-
-			const slice = await attachments.read('a1', { offset: 0, length: 5 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('hello');
-			await handle.close();
-		});
-
-		it('lists the attachments belonging to a record', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			const attachments = handle.attachments();
-			await attachments.write({
-				id: 'a1',
-				owner: { collection: 'notes', id: 'n1' },
-				contentType: 'text/plain',
-				content,
-			});
-			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
-
-			const owned = await attachments.listFor({ collection: 'notes', id: 'n1' });
-			expect(owned.map(r => r.id)).toEqual(['a1']);
-			await handle.close();
-		});
-
-		it('reports a missing artifact without making the record unreadable', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			await handle.collection('notes').insert({ id: 'n1', data: { title: 'has media' } });
-			const attachments = handle.attachments();
-			await attachments.write({
-				id: 'a1',
-				owner: { collection: 'notes', id: 'n1' },
-				contentType: 'text/plain',
-				content,
-			});
-
-			// Remove the artifact behind the package's back.
-			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a1');
-
-			expect((await attachments.availability('a1')).state).toBe('missing');
-			expect((await handle.collection('notes').get('n1')).data.title).toBe('has media');
-			await handle.close();
-		});
-
-		it('finds an orphaned artifact and a dangling reference', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			const attachments = handle.attachments();
-			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
-			await context.removeReferenceBehindTheScenes(handle.scopeKey, 'a1');
-
-			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
-			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a2');
-
-			const report = await attachments.reconcile();
-			expect(report.orphanedArtifacts).toEqual(['a1']);
-			expect(report.danglingReferences).toEqual(['a2']);
-
-			const removed = await attachments.reconcile({ removeOrphans: true });
-			expect(removed.removedArtifacts).toEqual(['a1']);
-			expect((await attachments.reconcile()).orphanedArtifacts).toEqual([]);
-			await handle.close();
-		});
-
-		it('rolls a reference back with its transaction', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			try {
-				await handle.transaction(async tx => {
-					await tx.collection('notes').insert({ id: 'n1', data: { title: 'x' } });
-					await tx.attachments().write({ id: 'a1', contentType: 'text/plain', content });
-					throw new Error('injected');
-				});
-			} catch {
-				// Expected.
-			}
-
-			expect(await handle.collection('notes').find('n1')).toBeNull();
-			// The reference is gone; the artifact on disk is not, which is
-			// exactly why reconciliation exists.
-			const report = await handle.attachments().reconcile();
-			expect(report.orphanedArtifacts).toEqual(['a1']);
-			await handle.close();
-		});
-
-		it('rejects an artifact over the size budget', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			const huge = Buffer.alloc(101 * 1024 * 1024).toString('base64');
-
-			let thrown: unknown;
-			try {
-				await handle.attachments().write({ id: 'big', contentType: 'application/octet-stream', content: huge });
-			} catch (error) {
-				thrown = error;
-			}
-			expect(isCode(thrown, DiagnosticCodes.ATTACHMENT_WRITE_FAILED)).toBe(true);
-			await handle.close();
-		});
-
-		it('removes artifacts when the scope is deleted', async () => {
-			const handle = await context.adapter.open(context.configFor(scope));
-			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
-			await handle.close();
-
-			const outcome = await context.adapter.deleteScopeData(context.scopeTargetFor(scope));
-			expect(outcome.removedArtifacts).toContain('a1');
-		});
-	});
-}
+import { DiagnosticCodes } from '../../contract/errors';
+import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
+import type { ConformanceContext } from './index';
+
+/** US7: artifacts the package owns, and the reconciliation that keeps them honest. */
+export function registerAttachmentConformance(context: ConformanceContext): void {
+	describe('conformance: attachments', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+		const content = bytesToBase64(utf8Bytes('hello attachment'));
+
+		it('stores a reference alongside the artifact', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			const reference = await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+
+			expect(reference.size).toBe(base64ToBytes(content).length);
+			expect(await attachments.read('a1')).toBe(content);
+			expect((await attachments.availability('a1')).state).toBe('available');
+			await handle.close();
+		});
+
+		it('reads a byte range without materialising the whole artifact', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
+
+			const slice = await attachments.read('a1', { offset: 0, length: 5 });
+			expect(utf8String(base64ToBytes(slice))).toBe('hello');
+			await handle.close();
+		});
+
+		it('lists the attachments belonging to a record', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
+
+			const owned = await attachments.listFor({ collection: 'notes', id: 'n1' });
+			expect(owned.map(r => r.id)).toEqual(['a1']);
+			await handle.close();
+		});
+
+		it('reports a missing artifact without making the record unreadable', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.collection('notes').insert({ id: 'n1', data: { title: 'has media' } });
+			const attachments = handle.attachments();
+			await attachments.write({
+				id: 'a1',
+				owner: { collection: 'notes', id: 'n1' },
+				contentType: 'text/plain',
+				content,
+			});
+
+			// Remove the artifact behind the package's back.
+			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a1');
+
+			expect((await attachments.availability('a1')).state).toBe('missing');
+			expect((await handle.collection('notes').get('n1')).data.title).toBe('has media');
+			await handle.close();
+		});
+
+		it('finds an orphaned artifact and a dangling reference', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const attachments = handle.attachments();
+			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
+			await context.removeReferenceBehindTheScenes(handle.scopeKey, 'a1');
+
+			await attachments.write({ id: 'a2', contentType: 'text/plain', content });
+			await context.removeArtifactBehindTheScenes(handle.scopeKey, 'a2');
+
+			const report = await attachments.reconcile();
+			expect(report.orphanedArtifacts).toEqual(['a1']);
+			expect(report.danglingReferences).toEqual(['a2']);
+
+			const removed = await attachments.reconcile({ removeOrphans: true });
+			expect(removed.removedArtifacts).toEqual(['a1']);
+			expect((await attachments.reconcile()).orphanedArtifacts).toEqual([]);
+			await handle.close();
+		});
+
+		it('rolls a reference back with its transaction', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			try {
+				await handle.transaction(async tx => {
+					await tx.collection('notes').insert({ id: 'n1', data: { title: 'x' } });
+					await tx.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+					throw new Error('injected');
+				});
+			} catch {
+				// Expected.
+			}
+
+			expect(await handle.collection('notes').find('n1')).toBeNull();
+			// The reference is gone; the artifact on disk is not, which is
+			// exactly why reconciliation exists.
+			const report = await handle.attachments().reconcile();
+			expect(report.orphanedArtifacts).toEqual(['a1']);
+			await handle.close();
+		});
+
+		it('rejects an artifact over the size budget', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const huge = bytesToBase64(new Uint8Array(101 * 1024 * 1024));
+
+			let thrown: unknown;
+			try {
+				await handle
+					.attachments()
+					.write({ id: 'big', contentType: 'application/octet-stream', content: huge });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.ATTACHMENT_WRITE_FAILED)).toBe(true);
+			await handle.close();
+		});
+
+		it('removes artifacts when the scope is deleted', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+			await handle.close();
+
+			const outcome = await context.adapter.deleteScopeData(context.scopeTargetFor(scope));
+			expect(outcome.removedArtifacts).toContain('a1');
+		});
+	});
+}