66 lines
2.6 KiB
TypeScript
66 lines
2.6 KiB
TypeScript
|
/**
|
||
|
|
* @module utils/idNormalization
|
||
|
|
* @description The 8.0 entity-id normalization layer. Every id that enters
|
||
|
|
* Brainy is coerced to a valid UUID, because a native engine maps ids to compact
|
||
|
|
* integers and requires real UUIDs (`encode()` rejects arbitrary strings).
|
||
|
|
*
|
||
|
|
* The rules (decided as AR.1 = "normalize"):
|
||
|
|
* - **No id supplied** → a fresh time-ordered {@link v7} UUID (sortable by
|
||
|
|
* creation time; friendly to the id↔int mapper and range scans).
|
||
|
|
* - **A valid UUID** → used as-is.
|
||
|
|
* - **Any other string** (a natural key like `'user-123'`) → a STABLE
|
||
|
|
* {@link v5} UUID derived from it, so the same key always maps to the same id
|
||
|
|
* and the caller can keep using their natural key on every read/relate while
|
||
|
|
* the engine only ever sees a UUID. The original string is preserved so reads
|
||
|
|
* can surface it.
|
||
|
|
*
|
||
|
|
* Two entry points: {@link coerceNewEntityId} at creation (add/relate), and
|
||
|
|
* {@link resolveEntityId} at lookup (get/update/remove/relate endpoints).
|
||
|
|
*/
|
||
|
|
import { v5, v7, isUUID } from '../universal/uuid.js'
|
||
|
|
|
||
|
|
/** Metadata key under which a caller's original (non-UUID) id is preserved. */
|
||
|
|
export const ORIGINAL_ID_KEY = '_originalId'
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @description The result of normalizing an id at creation time.
|
||
|
|
*/
|
||
|
|
export interface CoercedId {
|
||
|
|
/** The canonical UUID to store and hand to the engine. */
|
||
|
|
id: string
|
||
|
|
/** The caller's original string, present only when it was normalized (non-UUID). */
|
||
|
|
originalId?: string
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @description Normalize an id supplied at CREATION (add/relate). Generates a
|
||
|
|
* time-ordered UUID when none is given, passes a real UUID through, and maps any
|
||
|
|
* other string to a stable namespaced UUID (recording the original).
|
||
|
|
* @param id - The caller-supplied id, or undefined to auto-generate.
|
||
|
|
* @returns The canonical UUID and, when normalized, the original string.
|
||
|
|
* @example
|
||
|
|
* coerceNewEntityId() // → { id: <uuidv7> }
|
||
|
|
* coerceNewEntityId('user-123') // → { id: <stable uuidv5>, originalId: 'user-123' }
|
||
|
|
*/
|
||
|
|
export function coerceNewEntityId(id?: string | null): CoercedId {
|
||
|
|
if (id === undefined || id === null || id === '') {
|
||
|
|
return { id: v7() }
|
||
|
|
}
|
||
|
|
if (isUUID(id)) {
|
||
|
|
return { id }
|
||
|
|
}
|
||
|
|
return { id: v5(id), originalId: id }
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @description Normalize an id used for LOOKUP (get/update/remove/relate
|
||
|
|
* endpoints) to the same canonical UUID `coerceNewEntityId` produced — so a
|
||
|
|
* caller can read/relate by their natural key transparently. A real UUID passes
|
||
|
|
* through; any other string maps to its stable namespaced UUID.
|
||
|
|
* @param id - The id to resolve.
|
||
|
|
* @returns The canonical UUID.
|
||
|
|
*/
|
||
|
|
export function resolveEntityId(id: string): string {
|
||
|
|
return isUUID(id) ? id : v5(id)
|
||
|
|
}
|