@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/contract/errors.ts

@@ -1,76 +1,76 @@
-/**
- * Diagnostic codes.
- *
- * Stable identifiers so an app can choose a response without parsing a
- * message (FR-074, FR-082). Disk-full, filesystem-access, and corruption stay
- * distinct rather than collapsing into a generic write failure (FR-076) —
- * an app frees space for one, retries after unlock for another, and offers a
- * reset for the third.
- *
- * Full table with recommended recovery per code:
- * specs/008-rn-local-db-package/contracts/errors.md
- */
-
-export const DiagnosticCodes = {
-	// Configuration and scope
-	CONFIG_INVALID: 'CONFIG_INVALID',
-	INVALID_SCOPE: 'INVALID_SCOPE',
-	MIGRATION_CONFIG_INVALID: 'MIGRATION_CONFIG_INVALID',
-
-	// Open and lifecycle
-	OPEN_FAILED: 'OPEN_FAILED',
-	CLOSED_HANDLE: 'CLOSED_HANDLE',
-	SCOPE_DELETED: 'SCOPE_DELETED',
-	CORRUPTION: 'CORRUPTION',
-	STORAGE_ACCESS: 'STORAGE_ACCESS',
-
-	// Migration
-	MIGRATION_FAILED: 'MIGRATION_FAILED',
-	SCHEMA_DOWNGRADE: 'SCHEMA_DOWNGRADE',
-
-	// Records and writes
-	RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
-	RECORD_CONFLICT: 'RECORD_CONFLICT',
-	RECORD_TOO_LARGE: 'RECORD_TOO_LARGE',
-	BATCH_TOO_LARGE: 'BATCH_TOO_LARGE',
-	DISK_FULL: 'DISK_FULL',
-	WRITE_FAILED: 'WRITE_FAILED',
-
-	// Query
-	QUERY_INVALID: 'QUERY_INVALID',
-	PAGE_SIZE_INVALID: 'PAGE_SIZE_INVALID',
-	CURSOR_INVALID: 'CURSOR_INVALID',
-
-	// Transaction
-	TRANSACTION_FAILED: 'TRANSACTION_FAILED',
-	TRANSACTION_STATE: 'TRANSACTION_STATE',
-
-	// Attachments
-	ATTACHMENT_MISSING: 'ATTACHMENT_MISSING',
-	ATTACHMENT_OUT_OF_BOUNDS: 'ATTACHMENT_OUT_OF_BOUNDS',
-	ATTACHMENT_WRITE_FAILED: 'ATTACHMENT_WRITE_FAILED',
-	ATTACHMENT_UNDECRYPTABLE: 'ATTACHMENT_UNDECRYPTABLE',
-
-	// Encryption
-	KEY_INVALID: 'KEY_INVALID',
-	KEY_PROVIDER_FAILED: 'KEY_PROVIDER_FAILED',
-	ENCRYPTION_MISMATCH: 'ENCRYPTION_MISMATCH',
-	ENCRYPTION_UNAVAILABLE: 'ENCRYPTION_UNAVAILABLE',
-} as const;
-
-export type DiagnosticCode = (typeof DiagnosticCodes)[keyof typeof DiagnosticCodes];
-
-/**
- * Codes worth retrying. `KEY_PROVIDER_FAILED` is here because a locked device
- * is an expected condition, not a bug (FR-102).
- */
-export const RETRYABLE_CODES: ReadonlySet<DiagnosticCode> = new Set<DiagnosticCode>([
-	DiagnosticCodes.OPEN_FAILED,
-	DiagnosticCodes.DISK_FULL,
-	DiagnosticCodes.WRITE_FAILED,
-	DiagnosticCodes.STORAGE_ACCESS,
-	DiagnosticCodes.TRANSACTION_FAILED,
-	DiagnosticCodes.MIGRATION_FAILED,
-	DiagnosticCodes.ATTACHMENT_WRITE_FAILED,
-	DiagnosticCodes.KEY_PROVIDER_FAILED,
-]);
+/**
+ * Diagnostic codes.
+ *
+ * Stable identifiers so an app can choose a response without parsing a
+ * message (FR-074, FR-082). Disk-full, filesystem-access, and corruption stay
+ * distinct rather than collapsing into a generic write failure (FR-076) —
+ * an app frees space for one, retries after unlock for another, and offers a
+ * reset for the third.
+ *
+ * Full table with recommended recovery per code:
+ * specs/008-rn-local-db-package/contracts/errors.md
+ */
+
+export const DiagnosticCodes = {
+	// Configuration and scope
+	CONFIG_INVALID: 'CONFIG_INVALID',
+	INVALID_SCOPE: 'INVALID_SCOPE',
+	MIGRATION_CONFIG_INVALID: 'MIGRATION_CONFIG_INVALID',
+
+	// Open and lifecycle
+	OPEN_FAILED: 'OPEN_FAILED',
+	CLOSED_HANDLE: 'CLOSED_HANDLE',
+	SCOPE_DELETED: 'SCOPE_DELETED',
+	CORRUPTION: 'CORRUPTION',
+	STORAGE_ACCESS: 'STORAGE_ACCESS',
+
+	// Migration
+	MIGRATION_FAILED: 'MIGRATION_FAILED',
+	SCHEMA_DOWNGRADE: 'SCHEMA_DOWNGRADE',
+
+	// Records and writes
+	RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
+	RECORD_CONFLICT: 'RECORD_CONFLICT',
+	RECORD_TOO_LARGE: 'RECORD_TOO_LARGE',
+	BATCH_TOO_LARGE: 'BATCH_TOO_LARGE',
+	DISK_FULL: 'DISK_FULL',
+	WRITE_FAILED: 'WRITE_FAILED',
+
+	// Query
+	QUERY_INVALID: 'QUERY_INVALID',
+	PAGE_SIZE_INVALID: 'PAGE_SIZE_INVALID',
+	CURSOR_INVALID: 'CURSOR_INVALID',
+
+	// Transaction
+	TRANSACTION_FAILED: 'TRANSACTION_FAILED',
+	TRANSACTION_STATE: 'TRANSACTION_STATE',
+
+	// Attachments
+	ATTACHMENT_MISSING: 'ATTACHMENT_MISSING',
+	ATTACHMENT_OUT_OF_BOUNDS: 'ATTACHMENT_OUT_OF_BOUNDS',
+	ATTACHMENT_WRITE_FAILED: 'ATTACHMENT_WRITE_FAILED',
+	ATTACHMENT_UNDECRYPTABLE: 'ATTACHMENT_UNDECRYPTABLE',
+
+	// Encryption
+	KEY_INVALID: 'KEY_INVALID',
+	KEY_PROVIDER_FAILED: 'KEY_PROVIDER_FAILED',
+	ENCRYPTION_MISMATCH: 'ENCRYPTION_MISMATCH',
+	ENCRYPTION_UNAVAILABLE: 'ENCRYPTION_UNAVAILABLE',
+} as const;
+
+export type DiagnosticCode = (typeof DiagnosticCodes)[keyof typeof DiagnosticCodes];
+
+/**
+ * Codes worth retrying. `KEY_PROVIDER_FAILED` is here because a locked device
+ * is an expected condition, not a bug (FR-102).
+ */
+export const RETRYABLE_CODES: ReadonlySet<DiagnosticCode> = new Set<DiagnosticCode>([
+	DiagnosticCodes.OPEN_FAILED,
+	DiagnosticCodes.DISK_FULL,
+	DiagnosticCodes.WRITE_FAILED,
+	DiagnosticCodes.STORAGE_ACCESS,
+	DiagnosticCodes.TRANSACTION_FAILED,
+	DiagnosticCodes.MIGRATION_FAILED,
+	DiagnosticCodes.ATTACHMENT_WRITE_FAILED,
+	DiagnosticCodes.KEY_PROVIDER_FAILED,
+]);

package/src/contract/migration.ts

@@ -1,42 +1,42 @@
-/**
- * Versioned migrations.
- *
- * The package never writes a migration and never alters domain data except
- * through one the domain supplied (FR-056).
- */
-
-import type { Transaction } from './transaction';
-
-/** Low-level escape hatch for schema work a migration needs. */
-// 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>;
-};
-
-export type Migration = {
-	/** Unique, contiguous, and reaching the declared schemaVersion (FR-053). */
-	version: number;
-	migrate(context: MigrationContext): Promise<void>;
-};
-
-export type MigrationOutcome = 'applied' | 'failed';
-
-export type MigrationLedgerEntry = {
-	version: number;
-	attemptedAt: number;
-	outcome: MigrationOutcome;
-	/** A diagnostic code only — never a message, which could carry payload. */
-	failureCode?: string;
-};
-
-/**
- * Attached to a MIGRATION_FAILED error so an app can tell a transient failure
- * from a permanent one and choose retry, reset, or asking the user (FR-057c).
- */
-export type MigrationFailureDetail = {
-	recordedVersion: number;
-	failingVersion: number;
-	outcome: MigrationOutcome;
-};
+/**
+ * Versioned migrations.
+ *
+ * The package never writes a migration and never alters domain data except
+ * through one the domain supplied (FR-056).
+ */
+
+import type { Transaction } from './transaction';
+
+/** Low-level escape hatch for schema work a migration needs. */
+// 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>;
+};
+
+export type Migration = {
+	/** Unique, contiguous, and reaching the declared schemaVersion (FR-053). */
+	version: number;
+	migrate(context: MigrationContext): Promise<void>;
+};
+
+export type MigrationOutcome = 'applied' | 'failed';
+
+export type MigrationLedgerEntry = {
+	version: number;
+	attemptedAt: number;
+	outcome: MigrationOutcome;
+	/** A diagnostic code only — never a message, which could carry payload. */
+	failureCode?: string;
+};
+
+/**
+ * Attached to a MIGRATION_FAILED error so an app can tell a transient failure
+ * from a permanent one and choose retry, reset, or asking the user (FR-057c).
+ */
+export type MigrationFailureDetail = {
+	recordedVersion: number;
+	failingVersion: number;
+	outcome: MigrationOutcome;
+};

package/src/contract/query.ts

@@ -1,81 +1,81 @@
-/**
- * Query contract.
- *
- * A query carries no scope, because it cannot address one — scope is bound to
- * the handle and immutable (FR-008a). That absence is the isolation
- * guarantee, not a convention.
- */
-
-import type { StorableRecordData, StoredRecord } from './record';
-
-/** Values a filter may compare against. */
-export type FilterValue = string | number | boolean | null;
-
-export type ComparisonOperator =
-	| 'eq'
-	| 'ne'
-	| 'lt'
-	| 'lte'
-	| 'gt'
-	| 'gte'
-	| 'in'
-	| 'nin'
-	| 'between'
-	| 'isNull'
-	| 'isNotNull'
-	| 'exists';
-
-export type ComparisonNode =
-	| { op: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte'; field: string; value: FilterValue }
-	| { op: 'in' | 'nin'; field: string; value: FilterValue[] }
-	| { op: 'between'; field: string; value: [FilterValue, FilterValue] }
-	| { op: 'isNull' | 'isNotNull'; field: string }
-	/** Distinguishes an absent field from one holding null (FR-019). */
-	| { op: 'exists'; field: string; value: boolean };
-
-export type LogicalNode =
-	| { op: 'and'; nodes: FilterNode[] }
-	| { op: 'or'; nodes: FilterNode[] }
-	| { op: 'not'; node: FilterNode };
-
-export type FilterNode = ComparisonNode | LogicalNode;
-
-export type SortDirection = 'asc' | 'desc';
-
-export type SortKey = {
-	field: string;
-	direction?: SortDirection;
-};
-
-export type PageRequest = {
-	/** 1..500 (FR-036, FR-088). */
-	size: number;
-	/** Opaque keyset cursor from a previous page. */
-	cursor?: string;
-};
-
-export type Query = {
-	filter?: FilterNode;
-	sort?: SortKey[];
-	page?: PageRequest;
-	/** Soft-deleted records are excluded unless this is true (FR-021). */
-	includeSoftDeleted?: boolean;
-};
-
-export type ResultPage<T extends StorableRecordData = StorableRecordData> = {
-	records: StoredRecord<T>[];
-	/** Absent when there is no further page. */
-	cursor?: string;
-	hasMore: boolean;
-};
-
-/**
- * Development-only answer to "is this query covered by an index?" (FR-037).
- * Backed by EXPLAIN QUERY PLAN on the SQLite adapter.
- */
-export type IndexCoverageReport = {
-	collection: string;
-	usesIndex: boolean;
-	indexName?: string;
-	detail: string;
-};
+/**
+ * Query contract.
+ *
+ * A query carries no scope, because it cannot address one — scope is bound to
+ * the handle and immutable (FR-008a). That absence is the isolation
+ * guarantee, not a convention.
+ */
+
+import type { StorableRecordData, StoredRecord } from './record';
+
+/** Values a filter may compare against. */
+export type FilterValue = string | number | boolean | null;
+
+export type ComparisonOperator =
+	| 'eq'
+	| 'ne'
+	| 'lt'
+	| 'lte'
+	| 'gt'
+	| 'gte'
+	| 'in'
+	| 'nin'
+	| 'between'
+	| 'isNull'
+	| 'isNotNull'
+	| 'exists';
+
+export type ComparisonNode =
+	| { op: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte'; field: string; value: FilterValue }
+	| { op: 'in' | 'nin'; field: string; value: FilterValue[] }
+	| { op: 'between'; field: string; value: [FilterValue, FilterValue] }
+	| { op: 'isNull' | 'isNotNull'; field: string }
+	/** Distinguishes an absent field from one holding null (FR-019). */
+	| { op: 'exists'; field: string; value: boolean };
+
+export type LogicalNode =
+	| { op: 'and'; nodes: FilterNode[] }
+	| { op: 'or'; nodes: FilterNode[] }
+	| { op: 'not'; node: FilterNode };
+
+export type FilterNode = ComparisonNode | LogicalNode;
+
+export type SortDirection = 'asc' | 'desc';
+
+export type SortKey = {
+	field: string;
+	direction?: SortDirection;
+};
+
+export type PageRequest = {
+	/** 1..500 (FR-036, FR-088). */
+	size: number;
+	/** Opaque keyset cursor from a previous page. */
+	cursor?: string;
+};
+
+export type Query = {
+	filter?: FilterNode;
+	sort?: SortKey[];
+	page?: PageRequest;
+	/** Soft-deleted records are excluded unless this is true (FR-021). */
+	includeSoftDeleted?: boolean;
+};
+
+export type ResultPage<T extends StorableRecordData = StorableRecordData> = {
+	records: StoredRecord<T>[];
+	/** Absent when there is no further page. */
+	cursor?: string;
+	hasMore: boolean;
+};
+
+/**
+ * Development-only answer to "is this query covered by an index?" (FR-037).
+ * Backed by EXPLAIN QUERY PLAN on the SQLite adapter.
+ */
+export type IndexCoverageReport = {
+	collection: string;
+	usesIndex: boolean;
+	indexName?: string;
+	detail: string;
+};

package/src/contract/record.ts

@@ -1,51 +1,46 @@
-/**
- * Records and the four value conditions.
- *
- * The distinction FR-019 requires — record absent, field explicitly null,
- * field absent, record soft-deleted — is preserved because reads reconstruct
- * from the stored payload alone and never from projected columns. See
- * research.md R6.
- */
-
-import type { DeletionOutcome } from './attachment';
-
-/** Anything the package will store and hand back unchanged. */
-export type StorableValue =
-	| string
-	| number
-	| boolean
-	| null
-	| StorableValue[]
-	| { [key: string]: StorableValue };
-
-export type StorableRecordData = { [key: string]: StorableValue };
-
-export type RecordInput<T extends StorableRecordData = StorableRecordData> = {
-	id: string;
-	data: T;
-};
-
-export type StoredRecord<T extends StorableRecordData = StorableRecordData> = {
-	id: string;
-	data: T;
-	/** Present only when the collection declares timestamps (FR-020). */
-	createdAt?: number;
-	updatedAt?: number;
-	/** Present only when soft-deleted (FR-021). */
-	deletedAt?: number | null;
-};
-
-export type WriteOperation = 'created' | 'updated' | 'deleted' | 'restored';
-
-/** An upsert reports which it actually was (FR-026). */
-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;
-};
+/**
+ * Records and the four value conditions.
+ *
+ * The distinction FR-019 requires — record absent, field explicitly null,
+ * field absent, record soft-deleted — is preserved because reads reconstruct
+ * from the stored payload alone and never from projected columns. See
+ * research.md R6.
+ */
+
+import type { DeletionOutcome } from './attachment';
+
+/** Anything the package will store and hand back unchanged. */
+export type StorableValue =
+	string | number | boolean | null | StorableValue[] | { [key: string]: StorableValue };
+
+export type StorableRecordData = { [key: string]: StorableValue };
+
+export type RecordInput<T extends StorableRecordData = StorableRecordData> = {
+	id: string;
+	data: T;
+};
+
+export type StoredRecord<T extends StorableRecordData = StorableRecordData> = {
+	id: string;
+	data: T;
+	/** Present only when the collection declares timestamps (FR-020). */
+	createdAt?: number;
+	updatedAt?: number;
+	/** Present only when soft-deleted (FR-021). */
+	deletedAt?: number | null;
+};
+
+export type WriteOperation = 'created' | 'updated' | 'deleted' | 'restored';
+
+/** An upsert reports which it actually was (FR-026). */
+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/schema.ts

@@ -1,36 +1,36 @@
-/**
- * Collection schema: structure only.
- *
- * Declaring a field makes it queryable and projectable. It does NOT restrict
- * what a record may contain — undeclared fields are stored and returned
- * faithfully, they are simply not filterable or sortable (FR-017, FR-034).
- */
-
-export type FieldType = 'string' | 'number' | 'boolean' | 'timestamp';
-
-export type FieldDeclaration = {
-	name: string;
-	type: FieldType;
-	/** Whether the projected column tolerates SQL NULL. Purely a query concern. */
-	nullable?: boolean;
-};
-
-export type IndexDeclaration = {
-	name: string;
-	/** Must all reference declared fields (FR-006). */
-	fields: string[];
-	unique?: boolean;
-};
-
-export type CollectionSchema = {
-	name: string;
-	fields: FieldDeclaration[];
-	indexes?: IndexDeclaration[];
-	/**
-	 * Opt-in per collection, off by default. When on, deleted rows are
-	 * excluded from queries unless explicitly requested (FR-021).
-	 */
-	softDelete?: boolean;
-	/** When on, the package maintains createdAt / updatedAt (FR-020). */
-	timestamps?: boolean;
-};
+/**
+ * Collection schema: structure only.
+ *
+ * Declaring a field makes it queryable and projectable. It does NOT restrict
+ * what a record may contain — undeclared fields are stored and returned
+ * faithfully, they are simply not filterable or sortable (FR-017, FR-034).
+ */
+
+export type FieldType = 'string' | 'number' | 'boolean' | 'timestamp';
+
+export type FieldDeclaration = {
+	name: string;
+	type: FieldType;
+	/** Whether the projected column tolerates SQL NULL. Purely a query concern. */
+	nullable?: boolean;
+};
+
+export type IndexDeclaration = {
+	name: string;
+	/** Must all reference declared fields (FR-006). */
+	fields: string[];
+	unique?: boolean;
+};
+
+export type CollectionSchema = {
+	name: string;
+	fields: FieldDeclaration[];
+	indexes?: IndexDeclaration[];
+	/**
+	 * Opt-in per collection, off by default. When on, deleted rows are
+	 * excluded from queries unless explicitly requested (FR-021).
+	 */
+	softDelete?: boolean;
+	/** When on, the package maintains createdAt / updatedAt (FR-020). */
+	timestamps?: boolean;
+};

package/src/contract/scope.ts

@@ -1,36 +1,36 @@
-/**
- * Storage scope: the isolation boundary for all data.
- *
- * Components are opaque values the consuming app supplies. The package
- * composes, normalizes, and validates them but never interprets them, and
- * never invents one of its own (FR-008, FR-009).
- */
-
-export type ScopeKind = 'guest' | 'identity' | 'tenant' | 'workspace' | 'custom';
-
-/**
- * What an app supplies to name a scope.
- *
- * Every component is treated as sensitive (FR-014): none of these values
- * reaches disk, a log, or an error. Only the SHA-256 digest of the canonical
- * form does.
- */
-export type ScopeDescriptor = {
-	kind: ScopeKind;
-	/** Required for every kind except `guest`. */
-	id?: string;
-	tenant?: string;
-	app?: string;
-	environment?: string;
-	namespace?: string;
-};
-
-/** The resolved scope: a hex digest, plus the kind it came from. */
-export type ResolvedScope = {
-	/** SHA-256 hex of the canonical descriptor. Names the scope's directory. */
-	key: string;
-	kind: ScopeKind;
-};
-
-/** Where a scope sits in its lifecycle. Persisted in the catalog (FR-063). */
-export type ScopeDeletionState = 'active' | 'deleting';
+/**
+ * Storage scope: the isolation boundary for all data.
+ *
+ * Components are opaque values the consuming app supplies. The package
+ * composes, normalizes, and validates them but never interprets them, and
+ * never invents one of its own (FR-008, FR-009).
+ */
+
+export type ScopeKind = 'guest' | 'identity' | 'tenant' | 'workspace' | 'custom';
+
+/**
+ * What an app supplies to name a scope.
+ *
+ * Every component is treated as sensitive (FR-014): none of these values
+ * reaches disk, a log, or an error. Only the SHA-256 digest of the canonical
+ * form does.
+ */
+export type ScopeDescriptor = {
+	kind: ScopeKind;
+	/** Required for every kind except `guest`. */
+	id?: string;
+	tenant?: string;
+	app?: string;
+	environment?: string;
+	namespace?: string;
+};
+
+/** The resolved scope: a hex digest, plus the kind it came from. */
+export type ResolvedScope = {
+	/** SHA-256 hex of the canonical descriptor. Names the scope's directory. */
+	key: string;
+	kind: ScopeKind;
+};
+
+/** Where a scope sits in its lifecycle. Persisted in the catalog (FR-063). */
+export type ScopeDeletionState = 'active' | 'deleting';