@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/platform/fs.ts

@@ -1,89 +1,89 @@
-/**
- * The filesystem peer, behind one lazy accessor.
- *
- * Required lazily for the same reason the engine is: a consuming app that
- * only ever runs the in-memory adapter in tests must not have to install a
- * native module to import this package. Confining the require to `platform/`
- * also keeps the native surface four directories wide, which is the layering
- * rule the ESLint config enforces.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-
-export type FileStat = {
-	path: string;
-	size: number;
-	mtime: number;
-	isFile(): boolean;
-	isDirectory(): boolean;
-};
-
-export type MkdirOptions = {
-	/** iOS only. Set at creation so nothing beneath it is ever backed up. */
-	NSURLIsExcludedFromBackupKey?: boolean;
-};
-
-/**
- * Only what the package actually uses. The peer's upload and download
- * helpers are deliberately absent from this type: the package must never
- * make a network request (FR-084, SC-016), and a surface that cannot express
- * one is a stronger guarantee than a rule that says not to.
- */
-export type FileSystem = {
-	DocumentDirectoryPath: string;
-	mkdir(path: string, options?: MkdirOptions): Promise<void>;
-	writeFile(path: string, contents: string, encoding?: string): Promise<void>;
-	appendFile(path: string, contents: string, encoding?: string): Promise<void>;
-	readFile(path: string, encoding?: string): Promise<string>;
-	/** Chunked read at an offset — what FR-107a's flat memory bound rests on. */
-	read(path: string, length: number, position: number, encoding?: string): Promise<string>;
-	stat(path: string): Promise<FileStat>;
-	readdir(path: string): Promise<string[]>;
-	unlink(path: string): Promise<void>;
-	exists(path: string): Promise<boolean>;
-};
-
-let override: FileSystem | null = null;
-let cached: FileSystem | null = null;
-
-/** Swap the peer. Tests and the demo app's in-memory mode only. */
-export function setFileSystem(module: FileSystem | null): void {
-	override = module;
-	cached = null;
-}
-
-export function fileSystem(): FileSystem {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('@dr.pogodin/react-native-fs') as FileSystem;
-		} catch (error) {
-			raise(DiagnosticCodes.STORAGE_ACCESS, {
-				message: 'filesystem peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
-}
-
-export async function pathExists(path: string): Promise<boolean> {
-	try {
-		return await fileSystem().exists(path);
-	} catch {
-		return false;
-	}
-}
-
-/** Remove a path, treating "already gone" as success (FR-062). */
-export async function removeIfPresent(path: string): Promise<boolean> {
-	try {
-		await fileSystem().unlink(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
+/**
+ * The filesystem peer, behind one lazy accessor.
+ *
+ * Required lazily for the same reason the engine is: a consuming app that
+ * only ever runs the in-memory adapter in tests must not have to install a
+ * native module to import this package. Confining the require to `platform/`
+ * also keeps the native surface four directories wide, which is the layering
+ * rule the ESLint config enforces.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+export type FileStat = {
+	path: string;
+	size: number;
+	mtime: number;
+	isFile(): boolean;
+	isDirectory(): boolean;
+};
+
+export type MkdirOptions = {
+	/** iOS only. Set at creation so nothing beneath it is ever backed up. */
+	NSURLIsExcludedFromBackupKey?: boolean;
+};
+
+/**
+ * Only what the package actually uses. The peer's upload and download
+ * helpers are deliberately absent from this type: the package must never
+ * make a network request (FR-084, SC-016), and a surface that cannot express
+ * one is a stronger guarantee than a rule that says not to.
+ */
+export type FileSystem = {
+	DocumentDirectoryPath: string;
+	mkdir(path: string, options?: MkdirOptions): Promise<void>;
+	writeFile(path: string, contents: string, encoding?: string): Promise<void>;
+	appendFile(path: string, contents: string, encoding?: string): Promise<void>;
+	readFile(path: string, encoding?: string): Promise<string>;
+	/** Chunked read at an offset — what FR-107a's flat memory bound rests on. */
+	read(path: string, length: number, position: number, encoding?: string): Promise<string>;
+	stat(path: string): Promise<FileStat>;
+	readdir(path: string): Promise<string[]>;
+	unlink(path: string): Promise<void>;
+	exists(path: string): Promise<boolean>;
+};
+
+let override: FileSystem | null = null;
+let cached: FileSystem | null = null;
+
+/** Swap the peer. Tests and the demo app's in-memory mode only. */
+export function setFileSystem(module: FileSystem | null): void {
+	override = module;
+	cached = null;
+}
+
+export function fileSystem(): FileSystem {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		try {
+			cached = require('@dr.pogodin/react-native-fs') as FileSystem;
+		} catch (error) {
+			raise(DiagnosticCodes.STORAGE_ACCESS, {
+				message: 'filesystem peer is not installed',
+				cause: error,
+			});
+		}
+	}
+	return cached!;
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+	try {
+		return await fileSystem().exists(path);
+	} catch {
+		return false;
+	}
+}
+
+/** Remove a path, treating "already gone" as success (FR-062). */
+export async function removeIfPresent(path: string): Promise<boolean> {
+	try {
+		await fileSystem().unlink(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

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,57 +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';
-
-/** 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');
-}
-
-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,
+			},
+		});
+	}
+}