@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/scope/normalize.ts

@@ -1,90 +1,83 @@
-/**
- * Scope descriptor normalization.
- *
- * The package normalizes and validates; it never repairs. A component it
- * cannot represent safely is an error (FR-013), because silently sanitizing
- * one is how two different descriptors end up sharing a directory — which
- * would be a cross-scope leak dressed up as a convenience.
- */
-
-import type { ScopeDescriptor, ScopeKind } from '../contract/scope';
-
-/**
- * Separates components in the canonical form.
- *
- * NUL rather than a printable character: a component containing the separator
- * could forge another descriptor's canonical string, and every printable
- * candidate occurs in legitimate identity data. Tenant names contain spaces,
- * identifiers contain colons and slashes, emails contain "@" and ".". NUL
- * occurs in none of them, so reserving it costs consumers nothing.
- */
-export const COMPONENT_SEPARATOR = '\u0000';
-
-/**
- * Control characters are rejected wholesale rather than only the separator.
- * They have no place in an identity component, and they would be trouble in a
- * log line or a diagnostic even where they could not forge a canonical
- * string.
- */
-// eslint-disable-next-line no-control-regex
-export const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
-
-export const MAX_COMPONENT_BYTES = 512;
-
-/** Fixed order, so the canonical form is stable across callers. */
-export const COMPONENT_ORDER = [
-	'kind',
-	'id',
-	'tenant',
-	'app',
-	'environment',
-	'namespace',
-] as const;
-
-export const SCOPE_KINDS: readonly ScopeKind[] = [
-	'guest',
-	'identity',
-	'tenant',
-	'workspace',
-	'custom',
-];
-
-/**
- * NFC, trimmed, case preserved.
- *
- * Case is preserved deliberately: the package does not know whether a
- * consumer's identity system is case-sensitive, and folding case would merge
- * two scopes the app considers distinct.
- */
-export function normalizeComponent(value: string): string {
-	return value.normalize('NFC').trim();
-}
-
-export type NormalizedScope = {
-	kind: ScopeKind;
-	components: Record<string, string>;
-	canonical: string;
-};
-
-/** Normalize without validating. Callers must validate first. */
-export function normalizeDescriptor(descriptor: ScopeDescriptor): NormalizedScope {
-	const components: Record<string, string> = {};
-	const parts: string[] = [];
-
-	for (const key of COMPONENT_ORDER) {
-		const raw = descriptor[key as keyof ScopeDescriptor];
-		if (typeof raw !== 'string' || raw.length === 0) {
-			parts.push('');
-			continue;
-		}
-		const normalized = normalizeComponent(raw);
-		components[key] = normalized;
-		parts.push(normalized);
-	}
-
-	return {
-		kind: descriptor.kind,
-		components,
-		canonical: parts.join(COMPONENT_SEPARATOR),
-	};
-}
+/**
+ * Scope descriptor normalization.
+ *
+ * The package normalizes and validates; it never repairs. A component it
+ * cannot represent safely is an error (FR-013), because silently sanitizing
+ * one is how two different descriptors end up sharing a directory — which
+ * would be a cross-scope leak dressed up as a convenience.
+ */
+
+import type { ScopeDescriptor, ScopeKind } from '../contract/scope';
+
+/**
+ * Separates components in the canonical form.
+ *
+ * NUL rather than a printable character: a component containing the separator
+ * could forge another descriptor's canonical string, and every printable
+ * candidate occurs in legitimate identity data. Tenant names contain spaces,
+ * identifiers contain colons and slashes, emails contain "@" and ".". NUL
+ * occurs in none of them, so reserving it costs consumers nothing.
+ */
+export const COMPONENT_SEPARATOR = '\u0000';
+
+/**
+ * Control characters are rejected wholesale rather than only the separator.
+ * They have no place in an identity component, and they would be trouble in a
+ * log line or a diagnostic even where they could not forge a canonical
+ * string.
+ */
+// eslint-disable-next-line no-control-regex
+export const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+
+export const MAX_COMPONENT_BYTES = 512;
+
+/** Fixed order, so the canonical form is stable across callers. */
+export const COMPONENT_ORDER = ['kind', 'id', 'tenant', 'app', 'environment', 'namespace'] as const;
+
+export const SCOPE_KINDS: readonly ScopeKind[] = [
+	'guest',
+	'identity',
+	'tenant',
+	'workspace',
+	'custom',
+];
+
+/**
+ * NFC, trimmed, case preserved.
+ *
+ * Case is preserved deliberately: the package does not know whether a
+ * consumer's identity system is case-sensitive, and folding case would merge
+ * two scopes the app considers distinct.
+ */
+export function normalizeComponent(value: string): string {
+	return value.normalize('NFC').trim();
+}
+
+export type NormalizedScope = {
+	kind: ScopeKind;
+	components: Record<string, string>;
+	canonical: string;
+};
+
+/** Normalize without validating. Callers must validate first. */
+export function normalizeDescriptor(descriptor: ScopeDescriptor): NormalizedScope {
+	const components: Record<string, string> = {};
+	const parts: string[] = [];
+
+	for (const key of COMPONENT_ORDER) {
+		const raw = descriptor[key as keyof ScopeDescriptor];
+		if (typeof raw !== 'string' || raw.length === 0) {
+			parts.push('');
+			continue;
+		}
+		const normalized = normalizeComponent(raw);
+		components[key] = normalized;
+		parts.push(normalized);
+	}
+
+	return {
+		kind: descriptor.kind,
+		components,
+		canonical: parts.join(COMPONENT_SEPARATOR),
+	};
+}

package/src/scope/validate.ts

@@ -1,83 +1,83 @@
-/**
- * Scope validation and resolution.
- *
- * Validate, never repair (FR-013). The package never invents, derives, or
- * defaults an identity of its own (FR-008).
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import type { ResolvedScope, ScopeDescriptor } from '../contract/scope';
-import { raise } from '../diagnostics/errors';
-import { sha256Hex, utf8ByteLength } from './hash';
-import {
-	COMPONENT_ORDER,
-	CONTROL_CHARACTER,
-	MAX_COMPONENT_BYTES,
-	SCOPE_KINDS,
-	normalizeComponent,
-	normalizeDescriptor,
-} from './normalize';
-
-function invalid(reason: string): never {
-	// The reason names the *component*, never its value — naming the value
-	// would put a scope component into an error, which FR-014 forbids.
-	raise(DiagnosticCodes.INVALID_SCOPE, { message: reason });
-}
-
-function validateComponent(key: string, raw: unknown): void {
-	if (raw === undefined || raw === null) {
-		return;
-	}
-	if (typeof raw !== 'string') {
-		invalid(`scope component ${key} must be a string`);
-	}
-	const normalized = normalizeComponent(raw);
-	if (normalized.length === 0) {
-		invalid(`scope component ${key} is empty after normalization`);
-	}
-	if (CONTROL_CHARACTER.test(normalized)) {
-		invalid(`scope component ${key} contains a control character`);
-	}
-	if (utf8ByteLength(normalized) > MAX_COMPONENT_BYTES) {
-		invalid(`scope component ${key} exceeds the maximum length`);
-	}
-}
-
-export function validateDescriptor(descriptor: ScopeDescriptor | undefined | null): void {
-	if (!descriptor || typeof descriptor !== 'object') {
-		invalid('scope descriptor is required');
-	}
-	if (!SCOPE_KINDS.includes(descriptor.kind)) {
-		invalid('scope kind is not recognised');
-	}
-
-	// Guest is the one kind with no identity, by design: an anonymous session
-	// still gets its own isolated scope rather than sharing a default.
-	if (descriptor.kind !== 'guest') {
-		const id = descriptor.id;
-		if (typeof id !== 'string' || normalizeComponent(id).length === 0) {
-			invalid('scope id is required for this kind');
-		}
-	}
-
-	for (const key of COMPONENT_ORDER) {
-		if (key === 'kind') {
-			continue;
-		}
-		validateComponent(key, descriptor[key as keyof ScopeDescriptor]);
-	}
-}
-
-/**
- * Deterministic: identical descriptors always resolve to the same scope, and
- * descriptors differing in any component always resolve to different ones
- * (FR-010).
- */
-export function resolveScope(descriptor: ScopeDescriptor): ResolvedScope {
-	validateDescriptor(descriptor);
-	const normalized = normalizeDescriptor(descriptor);
-	return {
-		key: sha256Hex(normalized.canonical),
-		kind: descriptor.kind,
-	};
-}
+/**
+ * Scope validation and resolution.
+ *
+ * Validate, never repair (FR-013). The package never invents, derives, or
+ * defaults an identity of its own (FR-008).
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { ResolvedScope, ScopeDescriptor } from '../contract/scope';
+import { raise } from '../diagnostics/errors';
+import { sha256Hex, utf8ByteLength } from './hash';
+import {
+	COMPONENT_ORDER,
+	CONTROL_CHARACTER,
+	MAX_COMPONENT_BYTES,
+	SCOPE_KINDS,
+	normalizeComponent,
+	normalizeDescriptor,
+} from './normalize';
+
+function invalid(reason: string): never {
+	// The reason names the *component*, never its value — naming the value
+	// would put a scope component into an error, which FR-014 forbids.
+	raise(DiagnosticCodes.INVALID_SCOPE, { message: reason });
+}
+
+function validateComponent(key: string, raw: unknown): void {
+	if (raw === undefined || raw === null) {
+		return;
+	}
+	if (typeof raw !== 'string') {
+		invalid(`scope component ${key} must be a string`);
+	}
+	const normalized = normalizeComponent(raw);
+	if (normalized.length === 0) {
+		invalid(`scope component ${key} is empty after normalization`);
+	}
+	if (CONTROL_CHARACTER.test(normalized)) {
+		invalid(`scope component ${key} contains a control character`);
+	}
+	if (utf8ByteLength(normalized) > MAX_COMPONENT_BYTES) {
+		invalid(`scope component ${key} exceeds the maximum length`);
+	}
+}
+
+export function validateDescriptor(descriptor: ScopeDescriptor | undefined | null): void {
+	if (!descriptor || typeof descriptor !== 'object') {
+		invalid('scope descriptor is required');
+	}
+	if (!SCOPE_KINDS.includes(descriptor.kind)) {
+		invalid('scope kind is not recognised');
+	}
+
+	// Guest is the one kind with no identity, by design: an anonymous session
+	// still gets its own isolated scope rather than sharing a default.
+	if (descriptor.kind !== 'guest') {
+		const id = descriptor.id;
+		if (typeof id !== 'string' || normalizeComponent(id).length === 0) {
+			invalid('scope id is required for this kind');
+		}
+	}
+
+	for (const key of COMPONENT_ORDER) {
+		if (key === 'kind') {
+			continue;
+		}
+		validateComponent(key, descriptor[key as keyof ScopeDescriptor]);
+	}
+}
+
+/**
+ * Deterministic: identical descriptors always resolve to the same scope, and
+ * descriptors differing in any component always resolve to different ones
+ * (FR-010).
+ */
+export function resolveScope(descriptor: ScopeDescriptor): ResolvedScope {
+	validateDescriptor(descriptor);
+	const normalized = normalizeDescriptor(descriptor);
+	return {
+		key: sha256Hex(normalized.canonical),
+		kind: descriptor.kind,
+	};
+}

package/src/sqlite/adapter.ts

@@ -1,26 +1,26 @@
-/**
- * The on-device adapter.
- *
- * Deliberately a seam rather than an implementation. Everything it composes
- * lives in `adapter/`, `migration/`, `artifacts/`, and this directory, so the
- * in-memory adapter can be held to the same contract by the same conformance
- * suite (FR-092) without either one being the "real" version the other
- * approximates.
- *
- * Reached only through the lazy require in `adapter/index.ts`, so a consumer
- * that runs the in-memory adapter in tests never loads the native peers.
- */
-
-import type { StorageAdapter } from '../contract/adapter';
-import { deleteDatabase, deleteScopeData, resetScope } from '../adapter/deletion';
-import { openSqliteDatabase, type OpenOptions } from '../adapter/lifecycle';
-
-export function createSqliteAdapter(options: OpenOptions = {}): StorageAdapter {
-	return {
-		name: 'sqlite',
-		open: config => openSqliteDatabase(config, options),
-		deleteScopeData,
-		deleteDatabase,
-		resetScope,
-	};
-}
+/**
+ * The on-device adapter.
+ *
+ * Deliberately a seam rather than an implementation. Everything it composes
+ * lives in `adapter/`, `migration/`, `artifacts/`, and this directory, so the
+ * in-memory adapter can be held to the same contract by the same conformance
+ * suite (FR-092) without either one being the "real" version the other
+ * approximates.
+ *
+ * Reached only through the lazy require in `adapter/index.ts`, so a consumer
+ * that runs the in-memory adapter in tests never loads the native peers.
+ */
+
+import type { StorageAdapter } from '../contract/adapter';
+import { deleteDatabase, deleteScopeData, resetScope } from '../adapter/deletion';
+import { openSqliteDatabase, type OpenOptions } from '../adapter/lifecycle';
+
+export function createSqliteAdapter(options: OpenOptions = {}): StorageAdapter {
+	return {
+		name: 'sqlite',
+		open: config => openSqliteDatabase(config, options),
+		deleteScopeData,
+		deleteDatabase,
+		resetScope,
+	};
+}