@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/platform/location.ts

@@ -1,135 +1,135 @@
-/**
- * The managed storage area, and the single guard every filesystem call routes
- * through.
- *
- * POL-011(b) flags media-and-files as a risk because this package deletes
- * files from disk on cascade. The mitigation is that there is exactly one
- * function that turns a caller's intent into a path, and it refuses anything
- * outside the root. One choke point is what makes SC-013a's filesystem
- * tracing pass reliably rather than usually.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-import { fileSystem } from './fs';
-
-export const MANAGED_ROOT_NAME = 'chipmobilesdk-localdb';
-export const CATALOG_FILE = 'catalog.db';
-export const SCOPES_DIR = 'scopes';
-export const DATA_FILE = 'data.db';
-export const ARTIFACTS_DIR = 'artifacts';
-export const MARKER_FILE = '.localdb-marker';
-
-/** Normalize separators and collapse redundant segments. No `..` survives. */
-export function normalizePath(path: string): string {
-	const unified = path.replace(/\\/g, '/');
-	const segments: string[] = [];
-	for (const segment of unified.split('/')) {
-		if (segment === '' || segment === '.') {
-			continue;
-		}
-		if (segment === '..') {
-			segments.pop();
-			continue;
-		}
-		segments.push(segment);
-	}
-	const prefix = unified.startsWith('/') ? '/' : '';
-	return prefix + segments.join('/');
-}
-
-export type StorageLayout = {
-	/** Absolute path to the managed root for one logical database. */
-	root: string;
-	catalogPath: string;
-	scopePath(scopeKey: string): string;
-	scopeDataPath(scopeKey: string): string;
-	scopeArtifactsPath(scopeKey: string): string;
-	artifactPath(scopeKey: string, attachmentId: string): string;
-	markerPath: string;
-};
-
-const SCOPE_KEY = /^[0-9a-f]{64}$/;
-const ARTIFACT_ID = /^[A-Za-z0-9._-]{1,128}$/;
-// `.` and `..` are made entirely of permitted characters and are the two that
-// matter: `artifacts/..` resolves to the scope directory itself, still inside
-// the managed root, so the boundary guard would wave it through and a cascade
-// would unlink the whole scope. A leading dot is refused with them, since no
-// attachment id needs one and hidden files are the package's own.
-const DOT_PREFIXED = /^\./;
-
-/**
- * An attachment id must be a safe single path segment.
- *
- * Shared by both adapters rather than left to the one that touches a
- * filesystem. The in-memory adapter has no paths to escape, but a consumer
- * whose tests accept `../../etc/passwd` and whose device build refuses it has
- * a test suite that stops predicting the device — which is the one thing the
- * adapter exists to avoid (FR-096).
- */
-export function assertValidAttachmentId(attachmentId: string): void {
-	if (!ARTIFACT_ID.test(attachmentId) || DOT_PREFIXED.test(attachmentId)) {
-		raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
-			message: 'attachment id is not a valid path segment',
-		});
-	}
-}
-
-export function createLayout(documentDirectory: string, databaseName: string): StorageLayout {
-	const root = normalizePath(`${documentDirectory}/${MANAGED_ROOT_NAME}/${databaseName}`);
-
-	const scopePath = (scopeKey: string): string => {
-		// The scope key is our own SHA-256 output. Validating its shape here
-		// means a caller cannot smuggle a traversal through it even if some
-		// future path reaches this function with unvalidated input.
-		if (!SCOPE_KEY.test(scopeKey)) {
-			raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
-				message: 'scope key is not a valid digest',
-			});
-		}
-		return `${root}/${SCOPES_DIR}/${scopeKey}`;
-	};
-
-	return {
-		root,
-		catalogPath: `${root}/${CATALOG_FILE}`,
-		markerPath: `${root}/${MARKER_FILE}`,
-		scopePath,
-		scopeDataPath: scopeKey => `${scopePath(scopeKey)}/${DATA_FILE}`,
-		scopeArtifactsPath: scopeKey => `${scopePath(scopeKey)}/${ARTIFACTS_DIR}`,
-		artifactPath: (scopeKey, attachmentId) => {
-			assertValidAttachmentId(attachmentId);
-			return `${scopePath(scopeKey)}/${ARTIFACTS_DIR}/${attachmentId}`;
-		},
-	};
-}
-
-/**
- * The layout for one logical database, rooted at the app's private documents
- * directory.
- *
- * Resolved lazily through the filesystem peer rather than captured at module
- * load, so importing this package does not require the peer to be installed —
- * a consumer running only the in-memory adapter never reaches this function.
- */
-export function layoutFor(databaseName: string): StorageLayout {
-	return createLayout(fileSystem().DocumentDirectoryPath, databaseName);
-}
-
-/**
- * The guard. Every read, write, and delete passes through this, and anything
- * resolving outside the managed root is refused before it reaches the
- * filesystem (FR-073, FR-073f).
- */
-export function assertWithinManagedArea(layout: StorageLayout, candidate: string): string {
-	const normalized = normalizePath(candidate);
-	const root = normalizePath(layout.root);
-	if (normalized !== root && !normalized.startsWith(`${root}/`)) {
-		raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
-			// The offending path is NOT reported: it may contain a scope
-			// component or a user-chosen filename.
-			message: 'path resolves outside the managed storage area',
-		});
-	}
-	return normalized;
-}
+/**
+ * The managed storage area, and the single guard every filesystem call routes
+ * through.
+ *
+ * POL-011(b) flags media-and-files as a risk because this package deletes
+ * files from disk on cascade. The mitigation is that there is exactly one
+ * function that turns a caller's intent into a path, and it refuses anything
+ * outside the root. One choke point is what makes SC-013a's filesystem
+ * tracing pass reliably rather than usually.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+import { fileSystem } from './fs';
+
+export const MANAGED_ROOT_NAME = 'chipmobilesdk-localdb';
+export const CATALOG_FILE = 'catalog.db';
+export const SCOPES_DIR = 'scopes';
+export const DATA_FILE = 'data.db';
+export const ARTIFACTS_DIR = 'artifacts';
+export const MARKER_FILE = '.localdb-marker';
+
+/** Normalize separators and collapse redundant segments. No `..` survives. */
+export function normalizePath(path: string): string {
+	const unified = path.replace(/\\/g, '/');
+	const segments: string[] = [];
+	for (const segment of unified.split('/')) {
+		if (segment === '' || segment === '.') {
+			continue;
+		}
+		if (segment === '..') {
+			segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const prefix = unified.startsWith('/') ? '/' : '';
+	return prefix + segments.join('/');
+}
+
+export type StorageLayout = {
+	/** Absolute path to the managed root for one logical database. */
+	root: string;
+	catalogPath: string;
+	scopePath(scopeKey: string): string;
+	scopeDataPath(scopeKey: string): string;
+	scopeArtifactsPath(scopeKey: string): string;
+	artifactPath(scopeKey: string, attachmentId: string): string;
+	markerPath: string;
+};
+
+const SCOPE_KEY = /^[0-9a-f]{64}$/;
+const ARTIFACT_ID = /^[A-Za-z0-9._-]{1,128}$/;
+// `.` and `..` are made entirely of permitted characters and are the two that
+// matter: `artifacts/..` resolves to the scope directory itself, still inside
+// the managed root, so the boundary guard would wave it through and a cascade
+// would unlink the whole scope. A leading dot is refused with them, since no
+// attachment id needs one and hidden files are the package's own.
+const DOT_PREFIXED = /^\./;
+
+/**
+ * An attachment id must be a safe single path segment.
+ *
+ * Shared by both adapters rather than left to the one that touches a
+ * filesystem. The in-memory adapter has no paths to escape, but a consumer
+ * whose tests accept `../../etc/passwd` and whose device build refuses it has
+ * a test suite that stops predicting the device — which is the one thing the
+ * adapter exists to avoid (FR-096).
+ */
+export function assertValidAttachmentId(attachmentId: string): void {
+	if (!ARTIFACT_ID.test(attachmentId) || DOT_PREFIXED.test(attachmentId)) {
+		raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+			message: 'attachment id is not a valid path segment',
+		});
+	}
+}
+
+export function createLayout(documentDirectory: string, databaseName: string): StorageLayout {
+	const root = normalizePath(`${documentDirectory}/${MANAGED_ROOT_NAME}/${databaseName}`);
+
+	const scopePath = (scopeKey: string): string => {
+		// The scope key is our own SHA-256 output. Validating its shape here
+		// means a caller cannot smuggle a traversal through it even if some
+		// future path reaches this function with unvalidated input.
+		if (!SCOPE_KEY.test(scopeKey)) {
+			raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+				message: 'scope key is not a valid digest',
+			});
+		}
+		return `${root}/${SCOPES_DIR}/${scopeKey}`;
+	};
+
+	return {
+		root,
+		catalogPath: `${root}/${CATALOG_FILE}`,
+		markerPath: `${root}/${MARKER_FILE}`,
+		scopePath,
+		scopeDataPath: scopeKey => `${scopePath(scopeKey)}/${DATA_FILE}`,
+		scopeArtifactsPath: scopeKey => `${scopePath(scopeKey)}/${ARTIFACTS_DIR}`,
+		artifactPath: (scopeKey, attachmentId) => {
+			assertValidAttachmentId(attachmentId);
+			return `${scopePath(scopeKey)}/${ARTIFACTS_DIR}/${attachmentId}`;
+		},
+	};
+}
+
+/**
+ * The layout for one logical database, rooted at the app's private documents
+ * directory.
+ *
+ * Resolved lazily through the filesystem peer rather than captured at module
+ * load, so importing this package does not require the peer to be installed —
+ * a consumer running only the in-memory adapter never reaches this function.
+ */
+export function layoutFor(databaseName: string): StorageLayout {
+	return createLayout(fileSystem().DocumentDirectoryPath, databaseName);
+}
+
+/**
+ * The guard. Every read, write, and delete passes through this, and anything
+ * resolving outside the managed root is refused before it reaches the
+ * filesystem (FR-073, FR-073f).
+ */
+export function assertWithinManagedArea(layout: StorageLayout, candidate: string): string {
+	const normalized = normalizePath(candidate);
+	const root = normalizePath(layout.root);
+	if (normalized !== root && !normalized.startsWith(`${root}/`)) {
+		raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+			// The offending path is NOT reported: it may contain a scope
+			// component or a user-chosen filename.
+			message: 'path resolves outside the managed storage area',
+		});
+	}
+	return normalized;
+}

package/src/query/budgets.ts

@@ -1,54 +1,54 @@
-/**
- * Budget enforcement.
- *
- * Per-record size, page size, and batch size are HARD limits reported through
- * typed errors (FR-088a). The rest are soft: exceeding them must not crash,
- * hang, or drop data silently, and the degraded behavior is documented.
- */
-
-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 ?? {});
-	return utf8Bytes(json).length;
-}
-
-export function assertRecordWithinBudget(collection: string, data: StorableRecordData): void {
-	const size = serializedSize(data);
-	if (size > Budgets.MAX_RECORD_BYTES) {
-		// Truncating would be silent data loss; failing opaquely would leave
-		// the consumer guessing. The size and the limit are both safe to
-		// report — neither can carry a field value.
-		raise(DiagnosticCodes.RECORD_TOO_LARGE, {
-			message: 'record exceeds the per-record size budget',
-			detail: { collection, sizeBytes: size, limitBytes: Budgets.MAX_RECORD_BYTES },
-		});
-	}
-}
-
-export function assertBatchWithinBudget(count: number): void {
-	if (count > Budgets.MAX_BATCH_OPERATIONS) {
-		raise(DiagnosticCodes.BATCH_TOO_LARGE, {
-			message: 'batch exceeds the operation budget',
-			detail: { count, limit: Budgets.MAX_BATCH_OPERATIONS },
-		});
-	}
-}
-
-export function assertArtifactWithinBudget(id: string, size: number): void {
-	if (size > Budgets.MAX_ARTIFACT_BYTES) {
-		raise(DiagnosticCodes.ATTACHMENT_WRITE_FAILED, {
-			message: 'artifact exceeds the size budget',
-			detail: {
-				attachmentId: id,
-				sizeBytes: size,
-				limitBytes: Budgets.MAX_ARTIFACT_BYTES,
-			},
-		});
-	}
-}
+/**
+ * Budget enforcement.
+ *
+ * Per-record size, page size, and batch size are HARD limits reported through
+ * typed errors (FR-088a). The rest are soft: exceeding them must not crash,
+ * hang, or drop data silently, and the degraded behavior is documented.
+ */
+
+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 ?? {});
+	return utf8Bytes(json).length;
+}
+
+export function assertRecordWithinBudget(collection: string, data: StorableRecordData): void {
+	const size = serializedSize(data);
+	if (size > Budgets.MAX_RECORD_BYTES) {
+		// Truncating would be silent data loss; failing opaquely would leave
+		// the consumer guessing. The size and the limit are both safe to
+		// report — neither can carry a field value.
+		raise(DiagnosticCodes.RECORD_TOO_LARGE, {
+			message: 'record exceeds the per-record size budget',
+			detail: { collection, sizeBytes: size, limitBytes: Budgets.MAX_RECORD_BYTES },
+		});
+	}
+}
+
+export function assertBatchWithinBudget(count: number): void {
+	if (count > Budgets.MAX_BATCH_OPERATIONS) {
+		raise(DiagnosticCodes.BATCH_TOO_LARGE, {
+			message: 'batch exceeds the operation budget',
+			detail: { count, limit: Budgets.MAX_BATCH_OPERATIONS },
+		});
+	}
+}
+
+export function assertArtifactWithinBudget(id: string, size: number): void {
+	if (size > Budgets.MAX_ARTIFACT_BYTES) {
+		raise(DiagnosticCodes.ATTACHMENT_WRITE_FAILED, {
+			message: 'artifact exceeds the size budget',
+			detail: {
+				attachmentId: id,
+				sizeBytes: size,
+				limitBytes: Budgets.MAX_ARTIFACT_BYTES,
+			},
+		});
+	}
+}

package/src/query/compare.ts

@@ -1,91 +1,91 @@
-/**
- * Comparison and field access semantics.
- *
- * Defined once here, used by the in-memory adapter directly and by the SQL
- * builder for validation and cursor construction. Two implementations of
- * these rules would drift, and the drift would show up as a conformance
- * divergence that hides a real bug (research.md R8).
- */
-
-import type { FilterValue } from '../contract/query';
-import type { StorableRecordData, StorableValue } from '../contract/record';
-
-/**
- * A field is one of three things, and the difference is the whole point of
- * FR-019: present with a value, present and null, or absent.
- */
-export type FieldLookup =
-	| { present: true; value: Exclude<StorableValue, null> }
-	| { present: true; value: null }
-	| { present: false };
-
-export function lookupField(data: StorableRecordData, field: string): FieldLookup {
-	if (!Object.prototype.hasOwnProperty.call(data, field)) {
-		return { present: false };
-	}
-	const value = data[field];
-	if (value === null) {
-		return { present: true, value: null };
-	}
-	return { present: true, value: value as Exclude<StorableValue, null> };
-}
-
-/**
- * Ordering for values of the same declared type.
- *
- * Null sorts before every non-null value, matching SQLite's default so the
- * two adapters agree without the SQL builder emitting NULLS FIRST/LAST
- * clauses that older SQLite versions do not support.
- */
-export function compareValues(a: FilterValue, b: FilterValue): number {
-	if (a === null && b === null) {
-		return 0;
-	}
-	if (a === null) {
-		return -1;
-	}
-	if (b === null) {
-		return 1;
-	}
-	if (typeof a === 'boolean' || typeof b === 'boolean') {
-		return Number(a) - Number(b);
-	}
-	if (typeof a === 'number' && typeof b === 'number') {
-		if (Number.isNaN(a) || Number.isNaN(b)) {
-			return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? -1 : 1;
-		}
-		return a < b ? -1 : a > b ? 1 : 0;
-	}
-	const sa = String(a);
-	const sb = String(b);
-	// Byte-order rather than locale collation: a locale-aware comparison would
-	// make the stored order depend on device settings, so the same data would
-	// page differently on two phones.
-	return sa < sb ? -1 : sa > sb ? 1 : 0;
-}
-
-/** Only primitives can be compared; a nested object is never a filter target. */
-export function asFilterValue(value: StorableValue): FilterValue | undefined {
-	if (
-		value === null ||
-		typeof value === 'string' ||
-		typeof value === 'number' ||
-		typeof value === 'boolean'
-	) {
-		return value;
-	}
-	return undefined;
-}
-
-/**
- * Byte order, not locale collation.
- *
- * A locale-aware sort would make the reported order depend on device
- * settings, so two phones holding identical data would report it differently.
- */
-export function byteOrder(a: string, b: string): number {
-	if (a < b) {
-		return -1;
-	}
-	return a > b ? 1 : 0;
-}
+/**
+ * Comparison and field access semantics.
+ *
+ * Defined once here, used by the in-memory adapter directly and by the SQL
+ * builder for validation and cursor construction. Two implementations of
+ * these rules would drift, and the drift would show up as a conformance
+ * divergence that hides a real bug (research.md R8).
+ */
+
+import type { FilterValue } from '../contract/query';
+import type { StorableRecordData, StorableValue } from '../contract/record';
+
+/**
+ * A field is one of three things, and the difference is the whole point of
+ * FR-019: present with a value, present and null, or absent.
+ */
+export type FieldLookup =
+	| { present: true; value: Exclude<StorableValue, null> }
+	| { present: true; value: null }
+	| { present: false };
+
+export function lookupField(data: StorableRecordData, field: string): FieldLookup {
+	if (!Object.prototype.hasOwnProperty.call(data, field)) {
+		return { present: false };
+	}
+	const value = data[field];
+	if (value === null) {
+		return { present: true, value: null };
+	}
+	return { present: true, value: value as Exclude<StorableValue, null> };
+}
+
+/**
+ * Ordering for values of the same declared type.
+ *
+ * Null sorts before every non-null value, matching SQLite's default so the
+ * two adapters agree without the SQL builder emitting NULLS FIRST/LAST
+ * clauses that older SQLite versions do not support.
+ */
+export function compareValues(a: FilterValue, b: FilterValue): number {
+	if (a === null && b === null) {
+		return 0;
+	}
+	if (a === null) {
+		return -1;
+	}
+	if (b === null) {
+		return 1;
+	}
+	if (typeof a === 'boolean' || typeof b === 'boolean') {
+		return Number(a) - Number(b);
+	}
+	if (typeof a === 'number' && typeof b === 'number') {
+		if (Number.isNaN(a) || Number.isNaN(b)) {
+			return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? -1 : 1;
+		}
+		return a < b ? -1 : a > b ? 1 : 0;
+	}
+	const sa = String(a);
+	const sb = String(b);
+	// Byte-order rather than locale collation: a locale-aware comparison would
+	// make the stored order depend on device settings, so the same data would
+	// page differently on two phones.
+	return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+
+/** Only primitives can be compared; a nested object is never a filter target. */
+export function asFilterValue(value: StorableValue): FilterValue | undefined {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'number' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	return undefined;
+}
+
+/**
+ * Byte order, not locale collation.
+ *
+ * A locale-aware sort would make the reported order depend on device
+ * settings, so two phones holding identical data would report it differently.
+ */
+export function byteOrder(a: string, b: string): number {
+	if (a < b) {
+		return -1;
+	}
+	return a > b ? 1 : 0;
+}