@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/adapter/transaction.ts

@@ -1,71 +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 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;
-		},
-	};
-}
+/**
+ * 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,67 +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 { 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 };
-}
+/**
+ * "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,114 +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 { 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),
-	);
-}
+/**
+ * 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));
+}