identifier

@fungi.computer/cairn

@fungi.computer/cairn / identifier

identifier

Classes

CairnDefinitionError

Bounded error thrown when a trusted family declaration violates Cairn’s version 1 definition invariants.

This error retains no rejected definition, family, kind, cause, or detail.

Extends

Error

Constructors

Constructor

new CairnDefinitionError(): CairnDefinitionError

Creates a fresh bounded family-definition error.

Returns

CairnDefinitionError

Overrides

Error.constructor

Properties

name

readonly name: "CairnDefinitionError" = "CairnDefinitionError"

Stable public error name.

Overrides

Error.name

code

readonly code: "invalid_definition" = "invalid_definition"

Stable machine-readable error discriminator.

CairnGenerationError

Bounded error thrown when secure entropy is unavailable during codec generation.

This error retains only validated family and kind metadata and never exposes a foreign cause, detail, or random bytes.

Extends

Error

Constructors

Constructor

new CairnGenerationError(input): CairnGenerationError

Creates a fresh bounded generation error.

Parameters

input

Readonly<{ family: string; kind: string; }>

Validated family and kind metadata for the failing codec.

Returns

CairnGenerationError

Overrides

Error.constructor

Properties

name

readonly name: "CairnGenerationError" = "CairnGenerationError"

Stable public error name.

Overrides

Error.name

code

readonly code: "entropy_unavailable" = "entropy_unavailable"

Stable machine-readable error discriminator.

family

readonly family: string

Validated family whose codec could not generate an identifier.

kind

readonly kind: string

Validated kind whose codec could not generate an identifier.

version

readonly version: 1 = 1

Wire grammar version used by the codec.

Interfaces

IdCodec

Generator and canonical parser for one declared identifier family and kind.

Type Parameters

F

F extends string

Declaring identifier family.

K

K extends string

Identifier kind within the family.

V

V extends 1 = 1

Retained wire grammar version; currently version 1.

Properties

family

readonly family: F

Declared identifier family; it is not serialized into metadata.

kind

readonly kind: K

Declared identifier kind; it is not serialized into metadata.

version

readonly version: V

Wire grammar version implemented by this codec.

Methods

generate()

generate(): CairnId<F, K, V>>

Generates one canonical identifier with a 21-character base36 suffix.

Returns

CairnId<F, K, V>

A fresh canonical identifier branded for this codec.

Throws

CairnGenerationError When secure entropy is unavailable.

parse()

parse(value): IdParseResult<CairnId<F, K, V>>, F, K>>

Parses an untrusted value without trimming, decoding, or normalization.

Parameters

value

unknown

Untrusted candidate value.

Returns

IdParseResult<CairnId<F, K, V>, F, K>

The original branded value or one bounded parse error.

is()

is(value): value is CairnId<F, K, V>

Reports whether an untrusted value is canonical for this codec.

Parameters

value

unknown

Untrusted candidate value.

Returns

value is CairnId<F, K, V>

Whether the value is accepted by IdCodec.parse.

Type Aliases

CairnId

CairnId<F, K, V> > = string & object

Canonical opaque identifier branded by its declaring family, kind, and wire grammar version.

Type Declaration

[cairnIdBrand]

readonly [cairnIdBrand]: readonly [F, K, V]

Compile-time identity metadata that is never serialized.

Type Parameters

F

F extends string

Declaring identifier family.

K

K extends string

Identifier kind within the family.

V

V extends 1 = 1

Retained wire grammar version; currently version 1.

IdOf

IdOf<C> > = C extends IdCodec<infer F, infer K, infer V> ? CairnId<F, K, V> > : never

Extracts the distinctly branded identifier produced by an ID codec.

Type Parameters

C

C

Codec whose identifier type is required.

IdParseError

IdParseError<F, K> > = Readonly<{ code: "invalid_id"; family: F; kind: K; version: 1; reason: "type" | "bounds" | "grammar" | "non_canonical"; }>

Bounded public description of a rejected identifier value.

The error deliberately retains neither the rejected value nor a foreign cause.

Type Parameters

F

F extends string

Declaring identifier family.

K

K extends string

Identifier kind within the family.

IdParseResult

IdParseResult<I, F, K> > = Readonly<{ ok: true; value: I; }> | Readonly<{ ok: false; error: IdParseError<F, K>>; }>

Successful canonical parsing or one bounded parse error.

Type Parameters

I

I

Branded identifier returned after successful parsing.

F

F extends string

Declaring identifier family.

K

K extends string

Identifier kind within the family.

IdKindDefinition

IdKindDefinition = Readonly<{ prefix: string; acceptedSuffixLength?: readonly [number, number]; }>

Trusted declaration for one identifier kind within a family.

IdFamily

IdFamily<F, D> > = Readonly<{ readonly [K in keyof D]: IdCodec<F, K & string, 1> }>>

Readonly family whose every own kind key maps to one distinctly branded version 1 codec.

Type Parameters

F

F extends string

Declaring identifier family.

D

D extends Readonly<Record<string, IdKindDefinition>>

Own identifier-kind declarations for the family.

Functions

defineIdFamily()

defineIdFamily<F, D>>(definition): IdFamily<F, D>>

Validates one trusted version 1 family declaration and creates its readonly family-scoped codecs.

Family and kind names, prefixes, compatibility ranges, own-key counts, and prefix uniqueness must satisfy the accepted Cairn invariants before any codec is returned.

Type Parameters

F

F extends string

Literal identifier-family name.

D

D extends Readonly<Record<string, Readonly<{ prefix: string; acceptedSuffixLength?: readonly [number, number]; }>>>

Literal own kind declarations for the family.

Parameters

definition

Readonly<{ family: F; version: 1; kinds: D; }>

Trusted version 1 family declaration to validate.

Returns

IdFamily<F, D>

One readonly codec property for every own kind key.

Throws

CairnDefinitionError When any declaration invariant or property access fails.