@chipmobilesdk/rn-local-db 0.1.2 → 0.2.0

package/src/artifacts/cascade.ts

@@ -14,7 +14,7 @@
  */
 
 import type { AttachmentOwner, DeletionOutcome } from '../contract/attachment';
-import { removeIfPresent } from '../platform/fs';
+import { fileSystem, removeIfPresent } from '../platform/fs';
 import type { Executor } from '../sqlite/connection';
 import { artifactPath } from './paths';
 import {
@@ -22,23 +22,54 @@ import {
 	listReferences,
 	listReferencesFor,
 	type ArtifactContext,
+	type DeferredUnlinks,
 } from './store';
 
+export type { DeferredUnlinks };
+
+/** Unlinks one artifact file. True when the file is gone afterwards, whoever removed it. */
+export async function unlinkArtifact(path: string): Promise<boolean> {
+	if (await removeIfPresent(path)) {
+		return true;
+	}
+	// `removeIfPresent` cannot tell "already gone" from "could not remove". A
+	// file that was already gone counts as removed: the end state the caller
+	// asked for is the end state they got.
+	try {
+		return !(await fileSystem().exists(path));
+	} catch {
+		return false;
+	}
+}
+
 async function removeAll(
 	context: ArtifactContext,
 	executor: Executor,
 	ids: string[],
+	deferred?: DeferredUnlinks,
 ): Promise<DeletionOutcome> {
 	const removedArtifacts: string[] = [];
 	const failedRemovals: string[] = [];
 
 	for (const id of ids) {
-		// A file that was already gone counts as removed: the end state the
-		// caller asked for is the end state they got.
-		await removeIfPresent(artifactPath(context.layout, context.scopeKey, id));
-		removedArtifacts.push(id);
+		// The reference first. A reference left pointing at a deleted file is
+		// the unrecoverable state; a file left without its reference is an
+		// orphan reconciliation finds.
 		if (!(await deleteReference(executor, id))) {
 			failedRemovals.push(id);
+			continue;
+		}
+		const path = artifactPath(context.layout, context.scopeKey, id);
+		if (deferred) {
+			deferred.add(path);
+			removedArtifacts.push(id);
+			continue;
+		}
+		if (await unlinkArtifact(path)) {
+			removedArtifacts.push(id);
+		} else {
+			// Still on disk holding the user's data: reported, never claimed removed.
+			failedRemovals.push(id);
 		}
 	}
 
@@ -50,17 +81,22 @@ async function removeAll(
 	};
 }
 
-/** Everything belonging to one record, for the FR-070 cascade. */
+/**
+ * Everything belonging to one record, for the FR-070 cascade. Inside a
+ * transaction pass `deferred`: the files are removed only once it commits.
+ */
 export async function cascadeForOwner(
 	context: ArtifactContext,
 	executor: Executor,
 	owner: AttachmentOwner,
+	deferred?: DeferredUnlinks,
 ): Promise<DeletionOutcome> {
 	const references = await listReferencesFor(executor, owner);
 	return removeAll(
 		context,
 		executor,
 		references.map(reference => reference.id),
+		deferred,
 	);
 }
 

package/src/artifacts/store.ts

@@ -28,6 +28,7 @@ import { isStorageError, raise } from '../diagnostics/errors';
 import { throwIfFaulted } from '../diagnostics/faults';
 import { raiseNative } from '../diagnostics/map-native';
 import { fileSystem, removeIfPresent } from '../platform/fs';
+import { base64ToBytes, bytesToBase64, concatBytes } from '../platform/bytes';
 import type { StorageLayout } from '../platform/location';
 import { assertArtifactWithinBudget } from '../query/budgets';
 import {
@@ -166,17 +167,17 @@ async function writePlaintext(path: string, content: string): Promise<void> {
 async function writeEncrypted(
 	path: string,
 	key: Uint8Array,
-	plaintext: Buffer,
+	plaintext: Uint8Array,
 ): Promise<{ chunkSize: number; chunkCount: number }> {
 	const header = headerFor(plaintext.length, Budgets.ARTIFACT_CHUNK_BYTES);
-	await fileSystem().writeFile(path, encodeHeader(header).toString('base64'), 'base64');
+	await fileSystem().writeFile(path, bytesToBase64(encodeHeader(header)), 'base64');
 
 	for (let index = 0; index < header.chunkCount; index += 1) {
 		const start = index * header.chunkSize;
 		const chunk = plaintext.subarray(start, start + chunkPlaintextLength(header, index));
 		await fileSystem().appendFile(
 			path,
-			encryptChunk(key, index, chunk).toString('base64'),
+			bytesToBase64(encryptChunk(key, index, chunk)),
 			'base64',
 		);
 	}
@@ -189,7 +190,7 @@ export async function writeArtifact(
 	input: AttachmentInput,
 ): Promise<AttachmentReference> {
 	throwIfFaulted('attachmentWrite');
-	const plaintext = Buffer.from(input.content, 'base64');
+	const plaintext = base64ToBytes(input.content);
 	assertArtifactWithinBudget(input.id, plaintext.length);
 
 	const path = artifactPath(context.layout, context.scopeKey, input.id);
@@ -241,10 +242,7 @@ async function readEncrypted(
 	key: Uint8Array,
 	range?: ByteRange,
 ): Promise<string> {
-	const headerBytes = Buffer.from(
-		await fileSystem().read(path, HEADER_BYTES, 0, 'base64'),
-		'base64',
-	);
+	const headerBytes = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
 	const header = decodeHeader(headerBytes);
 
 	const from = range?.offset ?? 0;
@@ -255,17 +253,16 @@ async function readEncrypted(
 
 	const first = Math.floor(from / header.chunkSize);
 	const last = Math.floor((to - 1) / header.chunkSize);
-	const pieces: Buffer[] = [];
+	const pieces: Uint8Array[] = [];
 
 	for (let index = first; index <= last; index += 1) {
-		const stored = Buffer.from(
+		const stored = base64ToBytes(
 			await fileSystem().read(
 				path,
 				chunkPlaintextLength(header, index) + TAG_BYTES,
 				chunkOffset(header, index),
 				'base64',
 			),
-			'base64',
 		);
 		const decrypted = decryptChunk(key, index, stored);
 		const chunkStart = index * header.chunkSize;
@@ -277,7 +274,7 @@ async function readEncrypted(
 		);
 	}
 
-	return Buffer.concat(pieces).toString('base64');
+	return bytesToBase64(concatBytes(pieces));
 }
 
 export async function readArtifact(
@@ -304,11 +301,36 @@ export async function readArtifact(
 	}
 }
 
+/**
+ * Collects file removals until the transaction that deleted their references
+ * commits. A file unlinked inside the transaction is gone even if the
+ * transaction then rolls back and the reference returns — a dangling
+ * reference to data nobody can recover.
+ */
+export type DeferredUnlinks = {
+	add(path: string): void;
+};
+
 export async function removeArtifact(
 	context: ArtifactContext,
 	id: string,
+	deferred?: DeferredUnlinks,
 ): Promise<DeletionOutcome> {
 	const path = artifactPath(context.layout, context.scopeKey, id);
+	if (deferred) {
+		// Inside a transaction: the reference goes now and rolls back with it;
+		// the file goes once the transaction commits.
+		const hadReference = await deleteReference(context.executor(), id);
+		if (hadReference) {
+			deferred.add(path);
+		}
+		return {
+			removedRecords: 0,
+			removedArtifacts: hadReference ? [id] : [],
+			orphanedReferences: [],
+			failedRemovals: [],
+		};
+	}
 	const removed = await removeIfPresent(path);
 	const hadReference = await deleteReference(context.executor(), id);
 

package/src/contract/attachment.ts

@@ -66,6 +66,12 @@ export type ReconciliationReport = {
 export type DeletionOutcome = {
 	scopeKey?: string;
 	removedRecords: number;
+	/**
+	 * True when the scope was deleted but its records could not be counted — an
+	 * encrypted scope whose key was unavailable, or a file that would not open.
+	 * `removedRecords` is then 0 and means "unknown". Added in 0.2.0.
+	 */
+	recordCountUnavailable?: boolean;
 	removedArtifacts: string[];
 	orphanedReferences: string[];
 	failedRemovals: string[];

package/src/contract/migration.ts

@@ -8,7 +8,9 @@
 import type { Transaction } from './transaction';
 
 /** Low-level escape hatch for schema work a migration needs. */
-export type MigrationContext = Transaction & {
+// Attachments are not part of a migration: a migration reshapes records, and
+// files written inside one would survive its rollback with nothing to own them.
+export type MigrationContext = Omit<Transaction, 'attachments'> & {
 	/** Execute a raw statement against the scope's database. */
 	execute(sql: string, params?: unknown[]): Promise<void>;
 };

package/src/contract/record.ts

@@ -7,6 +7,8 @@
  * research.md R6.
  */
 
+import type { DeletionOutcome } from './attachment';
+
 /** Anything the package will store and hand back unchanged. */
 export type StorableValue =
 	| string
@@ -39,4 +41,11 @@ export type WriteOperation = 'created' | 'updated' | 'deleted' | 'restored';
 export type WriteOutcome = {
 	operation: WriteOperation;
 	id: string;
+	/**
+	 * Present on a delete when `cascadeAttachments` is on: which attachment files
+	 * went with the record and which could not be removed (FR-071). Inside a
+	 * transaction the files are removed once it commits, so `removedArtifacts`
+	 * lists what was scheduled. Added in 0.2.0.
+	 */
+	cascade?: DeletionOutcome;
 };

package/src/contract/transaction.ts

@@ -8,6 +8,7 @@
 
 import type { FilterNode, Query, ResultPage } from './query';
 import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
+import type { Attachments } from './adapter';
 
 /** Collection operations, available on a handle and inside a transaction. */
 export type CollectionOps<T extends StorableRecordData = StorableRecordData> = {
@@ -29,6 +30,13 @@ export type Transaction = {
 	collection<T extends StorableRecordData = StorableRecordData>(
 		name: string,
 	): CollectionOps<T>;
+	/**
+	 * Attachments whose references join this transaction (FR-072): they roll
+	 * back with it, and cascaded files are removed only once it commits. Added
+	 * in 0.2.0 — the handle's own `attachments()` no longer reaches into an
+	 * in-flight transaction.
+	 */
+	attachments(): Attachments;
 	/** Discards every write in this transaction (FR-041). */
 	abort(): Promise<void>;
 };

package/src/crypto/chunked-cipher.ts

@@ -31,6 +31,7 @@ import { DiagnosticCodes } from '../contract/errors';
 import { raise } from '../diagnostics/errors';
 import { nonceForChunk } from './derive';
 import { cipherModule } from './provider';
+import { asciiAt, concatBytes } from '../platform/bytes';
 
 export const MAGIC = 'LDB1';
 export const FORMAT_VERSION = 1;
@@ -49,30 +50,35 @@ export function chunkCountFor(plaintextSize: number, chunkSize: number): number
 	return plaintextSize === 0 ? 0 : Math.ceil(plaintextSize / chunkSize);
 }
 
-export function encodeHeader(header: ArtifactHeader): Buffer {
-	const buffer = Buffer.alloc(HEADER_BYTES);
-	buffer.write(MAGIC, 0, 4, 'ascii');
-	buffer.writeUInt16BE(header.formatVersion, 4);
-	buffer.writeUInt32BE(header.chunkSize, 6);
-	buffer.writeUInt32BE(header.chunkCount, 10);
+export function encodeHeader(header: ArtifactHeader): Uint8Array {
+	const bytes = new Uint8Array(HEADER_BYTES);
+	for (let index = 0; index < 4; index += 1) {
+		bytes[index] = MAGIC.charCodeAt(index);
+	}
+	// Big-endian, as DataView writes by default; the on-disk format is unchanged.
+	const view = new DataView(bytes.buffer);
+	view.setUint16(4, header.formatVersion);
+	view.setUint32(6, header.chunkSize);
+	view.setUint32(10, header.chunkCount);
 	// Split across two 32-bit writes: artifact sizes stay well inside the safe
 	// integer range, and this avoids depending on BigInt in Hermes.
-	buffer.writeUInt32BE(Math.floor(header.plaintextSize / 0x100000000), 14);
-	buffer.writeUInt32BE(header.plaintextSize % 0x100000000, 18);
-	return buffer;
+	view.setUint32(14, Math.floor(header.plaintextSize / 0x100000000));
+	view.setUint32(18, header.plaintextSize % 0x100000000);
+	return bytes;
 }
 
-export function decodeHeader(buffer: Buffer): ArtifactHeader {
-	if (buffer.length < HEADER_BYTES || buffer.toString('ascii', 0, 4) !== MAGIC) {
+export function decodeHeader(bytes: Uint8Array): ArtifactHeader {
+	if (bytes.length < HEADER_BYTES || asciiAt(bytes, 0, 4) !== MAGIC) {
 		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
 			message: 'artifact header is not a recognised encrypted artifact',
 		});
 	}
+	const view = new DataView(bytes.buffer, bytes.byteOffset, HEADER_BYTES);
 	return {
-		formatVersion: buffer.readUInt16BE(4),
-		chunkSize: buffer.readUInt32BE(6),
-		chunkCount: buffer.readUInt32BE(10),
-		plaintextSize: buffer.readUInt32BE(14) * 0x100000000 + buffer.readUInt32BE(18),
+		formatVersion: view.getUint16(4),
+		chunkSize: view.getUint32(6),
+		chunkCount: view.getUint32(10),
+		plaintextSize: view.getUint32(14) * 0x100000000 + view.getUint32(18),
 	};
 }
 
@@ -102,16 +108,16 @@ export function encryptedLength(header: ArtifactHeader): number {
 }
 
 /** One chunk in, ciphertext with its tag appended out. */
-export function encryptChunk(key: Uint8Array, index: number, plaintext: Buffer): Buffer {
+export function encryptChunk(key: Uint8Array, index: number, plaintext: Uint8Array): Uint8Array {
 	const cipher = cipherModule().createCipheriv(ALGORITHM, key, nonceForChunk(index));
-	const body = Buffer.concat([
-		Buffer.from(cipher.update(plaintext)),
-		Buffer.from(cipher.final()),
+	return concatBytes([
+		new Uint8Array(cipher.update(plaintext)),
+		new Uint8Array(cipher.final()),
+		new Uint8Array(cipher.getAuthTag()),
 	]);
-	return Buffer.concat([body, Buffer.from(cipher.getAuthTag())]);
 }
 
-export function decryptChunk(key: Uint8Array, index: number, stored: Buffer): Buffer {
+export function decryptChunk(key: Uint8Array, index: number, stored: Uint8Array): Uint8Array {
 	if (stored.length < TAG_BYTES) {
 		raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
 			message: 'artifact chunk is truncated',
@@ -123,7 +129,7 @@ export function decryptChunk(key: Uint8Array, index: number, stored: Buffer): Bu
 	const decipher = cipherModule().createDecipheriv(ALGORITHM, key, nonceForChunk(index));
 	decipher.setAuthTag(tag);
 	try {
-		return Buffer.concat([Buffer.from(decipher.update(body)), Buffer.from(decipher.final())]);
+		return concatBytes([new Uint8Array(decipher.update(body)), new Uint8Array(decipher.final())]);
 	} catch (error) {
 		// A failing tag is the only signal that separates "exists but will not
 		// decrypt" from "missing", and an app responds to them differently.

package/src/crypto/derive.ts

@@ -14,13 +14,14 @@
  */
 
 import { cipherModule } from './provider';
+import { utf8Bytes } from '../platform/bytes';
 
 const HKDF_DIGEST = 'sha256';
 const KEY_BYTES = 32;
 const NONCE_BYTES = 12;
 
 function bytesOf(value: string): Uint8Array {
-	return Uint8Array.from(Buffer.from(value, 'utf8'));
+	return utf8Bytes(value);
 }
 
 /** 32 bytes, one artifact, one database key. */

package/src/platform/bytes.ts

@@ -0,0 +1,144 @@
+/**
+ * Byte handling without Node's `Buffer`.
+ *
+ * Hermes has no global `Buffer`, and `react-native-quick-crypto` installs one
+ * only when the app calls its `install()` — which nothing in this package or its
+ * documentation asked for. Until 0.2.0 attachment writes and reads used the
+ * global anyway, so on a device every attachment operation threw. Everything
+ * here is plain `Uint8Array` and a self-contained base64 codec, identical on
+ * Hermes and in Node.
+ */
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const LOOKUP = (() => {
+	const table = new Int16Array(128).fill(-1);
+	for (let index = 0; index < ALPHABET.length; index += 1) {
+		table[ALPHABET.charCodeAt(index)] = index;
+	}
+	// The URL-safe variants decode too, since some file APIs return them.
+	table['-'.charCodeAt(0)] = 62;
+	table['_'.charCodeAt(0)] = 63;
+	return table;
+})();
+
+/* eslint-disable no-bitwise -- base64 is bit packing; there is no clearer way to write it. */
+
+/** Characters per `String.fromCharCode` call; large spreads overflow the stack. */
+const CHUNK = 0x8000;
+
+export function base64ToBytes(base64: string): Uint8Array {
+	if (typeof globalThis.atob === 'function') {
+		let binary: string | undefined;
+		try {
+			binary = globalThis.atob(base64.replace(/-/g, '+').replace(/_/g, '/'));
+		} catch {
+			// atob is strict where Buffer was lenient; fall through to the
+			// tolerant decoder rather than turn stray characters into a crash.
+		}
+		if (binary !== undefined) {
+			const bytes = new Uint8Array(binary.length);
+			for (let index = 0; index < binary.length; index += 1) {
+				bytes[index] = binary.charCodeAt(index);
+			}
+			return bytes;
+		}
+	}
+	// Decode directly, skipping padding and anything outside the alphabet.
+	const bytes = new Uint8Array(Math.ceil((base64.length * 3) / 4));
+	let out = 0;
+	let buffer = 0;
+	let bits = 0;
+	for (let index = 0; index < base64.length; index += 1) {
+		const code = base64.charCodeAt(index);
+		const value = code < 128 ? LOOKUP[code]! : -1;
+		if (value < 0) continue;
+		buffer = (buffer << 6) | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes[out++] = (buffer >> bits) & 0xff;
+		}
+	}
+	return bytes.subarray(0, out);
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+	if (typeof globalThis.btoa === 'function') {
+		const parts: string[] = [];
+		for (let index = 0; index < bytes.length; index += CHUNK) {
+			parts.push(String.fromCharCode(...bytes.subarray(index, index + CHUNK)));
+		}
+		return globalThis.btoa(parts.join(''));
+	}
+	const parts: string[] = [];
+	for (let start = 0; start < bytes.length; start += CHUNK * 3) {
+		let piece = '';
+		const end = Math.min(bytes.length, start + CHUNK * 3);
+		let index = start;
+		for (; index + 2 < end; index += 3) {
+			const triple = (bytes[index]! << 16) | (bytes[index + 1]! << 8) | bytes[index + 2]!;
+			piece +=
+				ALPHABET[triple >> 18]! +
+				ALPHABET[(triple >> 12) & 63]! +
+				ALPHABET[(triple >> 6) & 63]! +
+				ALPHABET[triple & 63]!;
+		}
+		const remaining = end - index;
+		if (remaining === 1) {
+			const value = bytes[index]!;
+			piece += `${ALPHABET[value >> 2]}${ALPHABET[(value & 3) << 4]}==`;
+		} else if (remaining === 2) {
+			const value = (bytes[index]! << 8) | bytes[index + 1]!;
+			piece += `${ALPHABET[value >> 10]}${ALPHABET[(value >> 4) & 63]}${ALPHABET[(value & 15) << 2]}=`;
+		}
+		parts.push(piece);
+	}
+	return parts.join('');
+}
+
+/** UTF-8 encoding. `TextEncoder` is in Hermes and Node; the loop is the fallback. */
+export function utf8Bytes(value: string): Uint8Array {
+	if (typeof TextEncoder !== 'undefined') {
+		return new TextEncoder().encode(value);
+	}
+	const encoded = unescape(encodeURIComponent(value));
+	const bytes = new Uint8Array(encoded.length);
+	for (let index = 0; index < encoded.length; index += 1) {
+		bytes[index] = encoded.charCodeAt(index);
+	}
+	return bytes;
+}
+
+/** UTF-8 decoding, the inverse of `utf8Bytes`. */
+export function utf8String(bytes: Uint8Array): string {
+	if (typeof TextDecoder !== 'undefined') {
+		return new TextDecoder().decode(bytes);
+	}
+	let binary = '';
+	for (const byte of bytes) {
+		binary += String.fromCharCode(byte);
+	}
+	return decodeURIComponent(escape(binary));
+}
+
+/* eslint-enable no-bitwise */
+
+export function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const joined = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		joined.set(part, offset);
+		offset += part.length;
+	}
+	return joined;
+}
+
+/** The ASCII text of `length` bytes from `start`, for magic numbers. */
+export function asciiAt(bytes: Uint8Array, start: number, length: number): string {
+	let text = '';
+	for (let index = start; index < start + length && index < bytes.length; index += 1) {
+		text += String.fromCharCode(bytes[index]!);
+	}
+	return text;
+}

package/src/query/budgets.ts

@@ -10,15 +10,12 @@ import { Budgets } from '../contract/config';
 import { DiagnosticCodes } from '../contract/errors';
 import type { StorableRecordData } from '../contract/record';
 import { raise } from '../diagnostics/errors';
+import { utf8Bytes } from '../platform/bytes';
 
 /** UTF-8 byte length of the serialized payload — what actually hits disk. */
 export function serializedSize(data: StorableRecordData): number {
 	const json = JSON.stringify(data ?? {});
-	// TextEncoder is present in Hermes and in Node; Buffer is the fallback.
-	if (typeof TextEncoder !== 'undefined') {
-		return new TextEncoder().encode(json).length;
-	}
-	return Buffer.byteLength(json, 'utf8');
+	return utf8Bytes(json).length;
 }
 
 export function assertRecordWithinBudget(collection: string, data: StorableRecordData): void {

package/src/query/cursor.ts

@@ -14,6 +14,7 @@ import type { StoredRecord } from '../contract/record';
 import { raise } from '../diagnostics/errors';
 import { compareValues } from './compare';
 import { sortValueOf } from './sort';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../platform/bytes';
 
 export type CursorPayload = {
 	/** Sort key fields and directions, so a cursor cannot be reused across shapes. */
@@ -30,14 +31,14 @@ function toBase64(value: string): string {
 	if (typeof globalThis.btoa === 'function') {
 		return globalThis.btoa(unescape(encodeURIComponent(value)));
 	}
-	return Buffer.from(value, 'utf8').toString('base64');
+	return bytesToBase64(utf8Bytes(value));
 }
 
 function fromBase64(value: string): string {
 	if (typeof globalThis.atob === 'function') {
 		return decodeURIComponent(escape(globalThis.atob(value)));
 	}
-	return Buffer.from(value, 'base64').toString('utf8');
+	return utf8String(base64ToBytes(value));
 }
 
 export function encodeCursor(record: StoredRecord, sort: SortKey[]): string {