@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/adapter/transaction.ts

@@ -1,65 +1,71 @@
-/**
- * The `Transaction` a consumer actually holds.
- *
- * Two rules live here rather than in either adapter, so both are held to the
- * same standard:
- *
- * **Read-your-own-writes** (FR-043). Every collection reached through `tx`
- * runs against the transaction's executor, so a read inside sees the writes
- * made inside. A collection reached through the handle during a transaction
- * would not, and handing one out would be a quiet correctness trap.
- *
- * **Terminal state is terminal** (FR-044). After a commit or an abort, using
- * the transaction raises rather than silently writing outside it — the
- * failure mode where a caller's cleanup code lands in the database after the
- * rollback it was supposed to be part of.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import type { StorableRecordData } from '../contract/record';
-import type { CollectionOps, Transaction } from '../contract/transaction';
-import { raise } from '../diagnostics/errors';
-
-export type TransactionHost = {
-	collection<T extends StorableRecordData>(name: string): CollectionOps<T>;
-	rollback(): Promise<void>;
-};
-
-export type ManagedTransaction = {
-	transaction: Transaction;
-	/** True once the body committed or aborted. */
-	isSettled(): boolean;
-	settle(): void;
-};
-
-export function createTransaction(host: TransactionHost): ManagedTransaction {
-	let settled = false;
-
-	const assertLive = (): void => {
-		if (settled) {
-			raise(DiagnosticCodes.TRANSACTION_STATE, {
-				message: 'transaction already settled',
-			});
-		}
-	};
-
-	const transaction: Transaction = {
-		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
-			assertLive();
-			return host.collection<T>(name);
-		},
-		async abort(): Promise<void> {
-			assertLive();
-			settled = true;
-			await host.rollback();
-		},
-	};
-
-	return {
-		transaction,
-		isSettled: () => settled,
-		settle: () => {
-			settled = true;
-		},
-	};
-}
+/**
+ * The `Transaction` a consumer actually holds.
+ *
+ * Two rules live here rather than in either adapter, so both are held to the
+ * same standard:
+ *
+ * **Read-your-own-writes** (FR-043). Every collection reached through `tx`
+ * runs against the transaction's executor, so a read inside sees the writes
+ * made inside. A collection reached through the handle during a transaction
+ * would not, and handing one out would be a quiet correctness trap.
+ *
+ * **Terminal state is terminal** (FR-044). After a commit or an abort, using
+ * the transaction raises rather than silently writing outside it — the
+ * failure mode where a caller's cleanup code lands in the database after the
+ * rollback it was supposed to be part of.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { StorableRecordData } from '../contract/record';
+import type { CollectionOps, Transaction } from '../contract/transaction';
+import type { Attachments } from '../contract/adapter';
+import { raise } from '../diagnostics/errors';
+
+export type TransactionHost = {
+	collection<T extends StorableRecordData>(name: string): CollectionOps<T>;
+	attachments(): Attachments;
+	rollback(): Promise<void>;
+};
+
+export type ManagedTransaction = {
+	transaction: Transaction;
+	/** True once the body committed or aborted. */
+	isSettled(): boolean;
+	settle(): void;
+};
+
+export function createTransaction(host: TransactionHost): ManagedTransaction {
+	let settled = false;
+
+	const assertLive = (): void => {
+		if (settled) {
+			raise(DiagnosticCodes.TRANSACTION_STATE, {
+				message: 'transaction already settled',
+			});
+		}
+	};
+
+	const transaction: Transaction = {
+		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
+			assertLive();
+			return host.collection<T>(name);
+		},
+		attachments(): Attachments {
+			assertLive();
+			return host.attachments();
+		},
+		async abort(): Promise<void> {
+			assertLive();
+			settled = true;
+			await host.rollback();
+		},
+	};
+
+	return {
+		transaction,
+		isSettled: () => settled,
+		settle: () => {
+			settled = true;
+		},
+	};
+}

package/src/artifacts/availability.ts

@@ -1,69 +1,67 @@
-/**
- * "Is this artifact still there?", answered without opening it.
- *
- * `stat()` and, for an encrypted artifact, the 22-byte header. Never a
- * content byte and never a decryption (FR-073e, FR-107b). An availability
- * check that decrypted would make a gallery screen showing fifty thumbnails
- * decrypt fifty artifacts to answer a question none of them asked, and would
- * put key material in play for an operation that does not need it.
- *
- * The four states are deliberately four rather than two. `missing` is data
- * that is gone; `undecryptable` is data that exists under a key that does not
- * open it, which is often recoverable and always a different conversation to
- * have with the user (FR-107c).
- */
-
-import type { AttachmentAvailability } from '../contract/attachment';
-import { fileSystem } from '../platform/fs';
-import { HEADER_BYTES, MAGIC } from '../crypto/chunked-cipher';
-import type { Executor } from '../sqlite/connection';
-import { artifactPath } from './paths';
-import { readReference, type ArtifactContext } from './store';
-
-export async function artifactAvailability(
-	context: ArtifactContext,
-	executor: Executor,
-	id: string,
-): Promise<AttachmentAvailability> {
-	const reference = await readReference(executor, id);
-	if (!reference) {
-		// No reference is "missing" rather than an error: the caller asked
-		// about an artifact this scope does not claim to have.
-		return { id, state: 'missing' };
-	}
-
-	const path = artifactPath(context.layout, context.scopeKey, id);
-
-	let size: number;
-	try {
-		const stat = await fileSystem().stat(path);
-		if (!stat.isFile()) {
-			return { id, state: 'inaccessible' };
-		}
-		size = stat.size;
-	} catch {
-		return { id, state: 'missing' };
-	}
-
-	if (context.artifactKey(id) === null) {
-		return { id, state: 'available', size: reference.size };
-	}
-
-	if (size < HEADER_BYTES) {
-		return { id, state: 'undecryptable', size: reference.size };
-	}
-
-	try {
-		const header = Buffer.from(
-			await fileSystem().read(path, HEADER_BYTES, 0, 'base64'),
-			'base64',
-		);
-		if (header.toString('ascii', 0, 4) !== MAGIC) {
-			return { id, state: 'undecryptable', size: reference.size };
-		}
-	} catch {
-		return { id, state: 'inaccessible', size: reference.size };
-	}
-
-	return { id, state: 'available', size: reference.size };
-}
+/**
+ * "Is this artifact still there?", answered without opening it.
+ *
+ * `stat()` and, for an encrypted artifact, the 22-byte header. Never a
+ * content byte and never a decryption (FR-073e, FR-107b). An availability
+ * check that decrypted would make a gallery screen showing fifty thumbnails
+ * decrypt fifty artifacts to answer a question none of them asked, and would
+ * put key material in play for an operation that does not need it.
+ *
+ * The four states are deliberately four rather than two. `missing` is data
+ * that is gone; `undecryptable` is data that exists under a key that does not
+ * open it, which is often recoverable and always a different conversation to
+ * have with the user (FR-107c).
+ */
+
+import type { AttachmentAvailability } from '../contract/attachment';
+import { fileSystem } from '../platform/fs';
+import { asciiAt, base64ToBytes } from '../platform/bytes';
+import { HEADER_BYTES, MAGIC } from '../crypto/chunked-cipher';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath } from './paths';
+import { readReference, type ArtifactContext } from './store';
+
+export async function artifactAvailability(
+	context: ArtifactContext,
+	executor: Executor,
+	id: string,
+): Promise<AttachmentAvailability> {
+	const reference = await readReference(executor, id);
+	if (!reference) {
+		// No reference is "missing" rather than an error: the caller asked
+		// about an artifact this scope does not claim to have.
+		return { id, state: 'missing' };
+	}
+
+	const path = artifactPath(context.layout, context.scopeKey, id);
+
+	let size: number;
+	try {
+		const stat = await fileSystem().stat(path);
+		if (!stat.isFile()) {
+			return { id, state: 'inaccessible' };
+		}
+		size = stat.size;
+	} catch {
+		return { id, state: 'missing' };
+	}
+
+	if (context.artifactKey(id) === null) {
+		return { id, state: 'available', size: reference.size };
+	}
+
+	if (size < HEADER_BYTES) {
+		return { id, state: 'undecryptable', size: reference.size };
+	}
+
+	try {
+		const header = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
+		if (asciiAt(header, 0, 4) !== MAGIC) {
+			return { id, state: 'undecryptable', size: reference.size };
+		}
+	} catch {
+		return { id, state: 'inaccessible', size: reference.size };
+	}
+
+	return { id, state: 'available', size: reference.size };
+}

package/src/artifacts/cascade.ts

@@ -1,78 +1,114 @@
-/**
- * Cascading artifact removal.
- *
- * The package deletes the files, because the Q2 clarification made it the
- * owner of them (FR-073c). That is the single riskiest thing this package
- * does — POL-011(b)'s media-and-files row exists for it — so two rules hold
- * without exception: every path goes through the boundary guard in
- * `paths.ts`, and the outcome reports what was removed **and what could not
- * be**, never a bare success (FR-071).
- *
- * A failed removal is reported rather than retried or swallowed. A file the
- * package could not delete is still on disk holding the user's data, and an
- * app that told them "deleted" would have said something untrue.
- */
-
-import type { AttachmentOwner, DeletionOutcome } from '../contract/attachment';
-import { removeIfPresent } from '../platform/fs';
-import type { Executor } from '../sqlite/connection';
-import { artifactPath } from './paths';
-import {
-	deleteReference,
-	listReferences,
-	listReferencesFor,
-	type ArtifactContext,
-} from './store';
-
-async function removeAll(
-	context: ArtifactContext,
-	executor: Executor,
-	ids: string[],
-): 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);
-		if (!(await deleteReference(executor, id))) {
-			failedRemovals.push(id);
-		}
-	}
-
-	return {
-		removedRecords: 0,
-		removedArtifacts,
-		orphanedReferences: [],
-		failedRemovals,
-	};
-}
-
-/** Everything belonging to one record, for the FR-070 cascade. */
-export async function cascadeForOwner(
-	context: ArtifactContext,
-	executor: Executor,
-	owner: AttachmentOwner,
-): Promise<DeletionOutcome> {
-	const references = await listReferencesFor(executor, owner);
-	return removeAll(
-		context,
-		executor,
-		references.map(reference => reference.id),
-	);
-}
-
-/** Everything in the scope, for scope deletion. */
-export async function cascadeAll(
-	context: ArtifactContext,
-	executor: Executor,
-): Promise<DeletionOutcome> {
-	const references = await listReferences(executor);
-	return removeAll(
-		context,
-		executor,
-		references.map(reference => reference.id),
-	);
-}
+/**
+ * Cascading artifact removal.
+ *
+ * The package deletes the files, because the Q2 clarification made it the
+ * owner of them (FR-073c). That is the single riskiest thing this package
+ * does — POL-011(b)'s media-and-files row exists for it — so two rules hold
+ * without exception: every path goes through the boundary guard in
+ * `paths.ts`, and the outcome reports what was removed **and what could not
+ * be**, never a bare success (FR-071).
+ *
+ * A failed removal is reported rather than retried or swallowed. A file the
+ * package could not delete is still on disk holding the user's data, and an
+ * app that told them "deleted" would have said something untrue.
+ */
+
+import type { AttachmentOwner, DeletionOutcome } from '../contract/attachment';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath } from './paths';
+import {
+	deleteReference,
+	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) {
+		// 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);
+		}
+	}
+
+	return {
+		removedRecords: 0,
+		removedArtifacts,
+		orphanedReferences: [],
+		failedRemovals,
+	};
+}
+
+/**
+ * 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,
+	);
+}
+
+/** Everything in the scope, for scope deletion. */
+export async function cascadeAll(
+	context: ArtifactContext,
+	executor: Executor,
+): Promise<DeletionOutcome> {
+	const references = await listReferences(executor);
+	return removeAll(
+		context,
+		executor,
+		references.map(reference => reference.id),
+	);
+}

package/src/artifacts/paths.ts

@@ -1,29 +1,29 @@
-/**
- * Every artifact path, resolved through one guard.
- *
- * POL-011(b) flags media-and-files as a risk precisely because this package
- * deletes files from disk on cascade. The mitigation is structural rather
- * than procedural: no code in `artifacts/` builds a path by string
- * concatenation, and the one function that turns an attachment id into a path
- * refuses anything escaping the managed root (FR-073, FR-073f).
- *
- * That is what makes SC-013a's filesystem tracing pass reliably rather than
- * usually — there is no second path to audit.
- */
-
-import { assertWithinManagedArea, type StorageLayout } from '../platform/location';
-
-export function artifactsDirectory(layout: StorageLayout, scopeKey: string): string {
-	return assertWithinManagedArea(layout, layout.scopeArtifactsPath(scopeKey));
-}
-
-export function artifactPath(
-	layout: StorageLayout,
-	scopeKey: string,
-	attachmentId: string,
-): string {
-	// `layout.artifactPath` already rejects an id that is not a safe single
-	// path segment; the guard then re-checks the assembled result, so a change
-	// to either one alone cannot open a hole.
-	return assertWithinManagedArea(layout, layout.artifactPath(scopeKey, attachmentId));
-}
+/**
+ * Every artifact path, resolved through one guard.
+ *
+ * POL-011(b) flags media-and-files as a risk precisely because this package
+ * deletes files from disk on cascade. The mitigation is structural rather
+ * than procedural: no code in `artifacts/` builds a path by string
+ * concatenation, and the one function that turns an attachment id into a path
+ * refuses anything escaping the managed root (FR-073, FR-073f).
+ *
+ * That is what makes SC-013a's filesystem tracing pass reliably rather than
+ * usually — there is no second path to audit.
+ */
+
+import { assertWithinManagedArea, type StorageLayout } from '../platform/location';
+
+export function artifactsDirectory(layout: StorageLayout, scopeKey: string): string {
+	return assertWithinManagedArea(layout, layout.scopeArtifactsPath(scopeKey));
+}
+
+export function artifactPath(
+	layout: StorageLayout,
+	scopeKey: string,
+	attachmentId: string,
+): string {
+	// `layout.artifactPath` already rejects an id that is not a safe single
+	// path segment; the guard then re-checks the assembled result, so a change
+	// to either one alone cannot open a hole.
+	return assertWithinManagedArea(layout, layout.artifactPath(scopeKey, attachmentId));
+}

package/src/artifacts/reconcile.ts

@@ -1,63 +1,63 @@
-/**
- * Reconciliation: the two ways the database and the disk can disagree.
- *
- * An **orphaned artifact** is a file with no reference — left by a rolled-back
- * transaction, or by a crash between the write and the insert. A **dangling
- * reference** is the reverse: a row pointing at a file the operating system
- * reclaimed, or the user deleted through a file manager.
- *
- * App-triggered only (FR-073d). A background sweep would run during a user's
- * session without their knowledge, delete files it believes are orphans, and
- * have no way to distinguish "orphan" from "written by a transaction that has
- * not committed yet". Handing the trigger to the app makes that an explicit
- * decision at a moment the app knows is quiet.
- */
-
-import type { ReconciliationReport } from '../contract/attachment';
-import { fileSystem, removeIfPresent } from '../platform/fs';
-import { byteOrder } from '../query/compare';
-import type { Executor } from '../sqlite/connection';
-import { artifactPath, artifactsDirectory } from './paths';
-import { listReferences, type ArtifactContext } from './store';
-
-export type ReconcileOptions = {
-	/** Off by default: deleting a user's file is never an implied yes. */
-	removeOrphans?: boolean;
-};
-
-async function filesOnDisk(context: ArtifactContext): Promise<string[]> {
-	try {
-		return await fileSystem().readdir(artifactsDirectory(context.layout, context.scopeKey));
-	} catch {
-		// No directory means no artifacts, which is a valid answer rather than
-		// a failure — a scope that never wrote one never created it.
-		return [];
-	}
-}
-
-export async function reconcileArtifacts(
-	context: ArtifactContext,
-	executor: Executor,
-	options: ReconcileOptions = {},
-): Promise<ReconciliationReport> {
-	const references = await listReferences(executor);
-	const referenced = new Set(references.map(reference => reference.id));
-	const present = new Set(await filesOnDisk(context));
-
-	const orphanedArtifacts = [...present].filter(id => !referenced.has(id)).sort(byteOrder);
-	const danglingReferences = references
-		.filter(reference => !present.has(reference.id))
-		.map(reference => reference.id)
-		.sort(byteOrder);
-
-	const removedArtifacts: string[] = [];
-	if (options.removeOrphans) {
-		for (const id of orphanedArtifacts) {
-			if (await removeIfPresent(artifactPath(context.layout, context.scopeKey, id))) {
-				removedArtifacts.push(id);
-			}
-		}
-	}
-
-	return { orphanedArtifacts, danglingReferences, removedArtifacts };
-}
+/**
+ * Reconciliation: the two ways the database and the disk can disagree.
+ *
+ * An **orphaned artifact** is a file with no reference — left by a rolled-back
+ * transaction, or by a crash between the write and the insert. A **dangling
+ * reference** is the reverse: a row pointing at a file the operating system
+ * reclaimed, or the user deleted through a file manager.
+ *
+ * App-triggered only (FR-073d). A background sweep would run during a user's
+ * session without their knowledge, delete files it believes are orphans, and
+ * have no way to distinguish "orphan" from "written by a transaction that has
+ * not committed yet". Handing the trigger to the app makes that an explicit
+ * decision at a moment the app knows is quiet.
+ */
+
+import type { ReconciliationReport } from '../contract/attachment';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import { byteOrder } from '../query/compare';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath, artifactsDirectory } from './paths';
+import { listReferences, type ArtifactContext } from './store';
+
+export type ReconcileOptions = {
+	/** Off by default: deleting a user's file is never an implied yes. */
+	removeOrphans?: boolean;
+};
+
+async function filesOnDisk(context: ArtifactContext): Promise<string[]> {
+	try {
+		return await fileSystem().readdir(artifactsDirectory(context.layout, context.scopeKey));
+	} catch {
+		// No directory means no artifacts, which is a valid answer rather than
+		// a failure — a scope that never wrote one never created it.
+		return [];
+	}
+}
+
+export async function reconcileArtifacts(
+	context: ArtifactContext,
+	executor: Executor,
+	options: ReconcileOptions = {},
+): Promise<ReconciliationReport> {
+	const references = await listReferences(executor);
+	const referenced = new Set(references.map(reference => reference.id));
+	const present = new Set(await filesOnDisk(context));
+
+	const orphanedArtifacts = [...present].filter(id => !referenced.has(id)).sort(byteOrder);
+	const danglingReferences = references
+		.filter(reference => !present.has(reference.id))
+		.map(reference => reference.id)
+		.sort(byteOrder);
+
+	const removedArtifacts: string[] = [];
+	if (options.removeOrphans) {
+		for (const id of orphanedArtifacts) {
+			if (await removeIfPresent(artifactPath(context.layout, context.scopeKey, id))) {
+				removedArtifacts.push(id);
+			}
+		}
+	}
+
+	return { orphanedArtifacts, danglingReferences, removedArtifacts };
+}