identifier
Classes
Section titled “Classes”CairnDefinitionError
Section titled “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
Section titled “Extends”Error
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CairnDefinitionError():
CairnDefinitionError
Creates a fresh bounded family-definition error.
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Error.constructor
Properties
Section titled “Properties”
readonlyname:"CairnDefinitionError"="CairnDefinitionError"
Stable public error name.
Overrides
Section titled “Overrides”Error.name
readonlycode:"invalid_definition"="invalid_definition"
Stable machine-readable error discriminator.
CairnGenerationError
Section titled “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
Section titled “Extends”Error
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CairnGenerationError(
input):CairnGenerationError
Creates a fresh bounded generation error.
Parameters
Section titled “Parameters”Readonly<{ family: string; kind: string; }>
Validated family and kind metadata for the failing codec.
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Error.constructor
Properties
Section titled “Properties”
readonlyname:"CairnGenerationError"="CairnGenerationError"
Stable public error name.
Overrides
Section titled “Overrides”Error.name
readonlycode:"entropy_unavailable"="entropy_unavailable"
Stable machine-readable error discriminator.
family
Section titled “family”
readonlyfamily:string
Validated family whose codec could not generate an identifier.
readonlykind:string
Validated kind whose codec could not generate an identifier.
version
Section titled “version”
readonlyversion:1=1
Wire grammar version used by the codec.
Type Aliases
Section titled “Type Aliases”CairnId
Section titled “CairnId”CairnId<
F,K,V> > =string&object
Canonical opaque identifier branded by its declaring family, kind, and wire grammar version.
Type Declaration
Section titled “Type Declaration”[cairnIdBrand]
Section titled “[cairnIdBrand]”
readonly[cairnIdBrand]: readonly [F,K,V]
Compile-time identity metadata that is never serialized.
Type Parameters
Section titled “Type Parameters”F extends string
Declaring identifier family.
K extends string
Identifier kind within the family.
V extends 1 = 1
Retained wire grammar version; currently version 1.
IdOf<
C> > =CextendsIdCodec<infer F, infer K, infer V> ?CairnId<F,K,V> > :never
Extracts the distinctly branded identifier produced by an ID codec.
Type Parameters
Section titled “Type Parameters”C
Codec whose identifier type is required.
IdParseError
Section titled “IdParseError”IdParseError<
F,K> > =Readonly<{code:"invalid_id";family:F;kind:K;version:1;reason:"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
Section titled “Type Parameters”F extends string
Declaring identifier family.
K extends string
Identifier kind within the family.
IdParseResult
Section titled “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
Section titled “Type Parameters”I
Branded identifier returned after successful parsing.
F extends string
Declaring identifier family.
K extends string
Identifier kind within the family.
IdCodec
Section titled “IdCodec”IdCodec<
F,K,V> > =object
Generator and canonical parser for one declared identifier family and kind.
Type Parameters
Section titled “Type Parameters”F extends string
Declaring identifier family.
K extends string
Identifier kind within the family.
V extends 1 = 1
Retained wire grammar version; currently version 1.
Properties
Section titled “Properties”family
Section titled “family”
readonlyfamily:F
Declared identifier family; it is not serialized into metadata.
readonlykind:K
Declared identifier kind; it is not serialized into metadata.
version
Section titled “version”
readonlyversion:V
Wire grammar version implemented by this codec.
schema
Section titled “schema”
readonlyschema:z.ZodType<CairnId<F,K,V>>,string>>
Schema for the untrusted wire boundary; outputs this codec’s branded ID.
Methods
Section titled “Methods”generate()
Section titled “generate()”generate():
CairnId<F,K,V>>
Generates one canonical identifier with a 21-character base36 suffix.
Returns
Section titled “Returns”CairnId<F, K, V>
A fresh canonical identifier branded for this codec.
Throws
Section titled “Throws”CairnGenerationError When secure entropy is unavailable.
parse()
Section titled “parse()”parse(
value):IdParseResult<CairnId<F,K,V>>,F,K>>
Parses a decoded string candidate without trimming, decoding, or normalization.
Parameters
Section titled “Parameters”string
Decoded string candidate.
Returns
Section titled “Returns”IdParseResult<CairnId<F, K, V>, F,
K>
The original branded value or one bounded parse error.
is(
value):value is CairnId<F, K, V>
Reports whether a decoded string candidate is canonical for this codec.
Parameters
Section titled “Parameters”string
Decoded string candidate.
Returns
Section titled “Returns”value is CairnId<F, K, V>
Whether the value is accepted by IdCodec.parse.
IdKindDefinition
Section titled “IdKindDefinition”IdKindDefinition =
Readonly<{prefix:string; }>
Trusted declaration for one identifier kind within a family.
IdFamily
Section titled “IdFamily”IdFamily<
F,D> > =Readonly<{ readonly [K in keyof D]: IdCodec<F, K & string> }>>
Readonly family whose every own kind key maps to one distinctly branded version 1 codec.
Type Parameters
Section titled “Type Parameters”F extends string
Declaring identifier family.
D extends Readonly<Record<string,
IdKindDefinition>>
Own identifier-kind declarations for the family.
Functions
Section titled “Functions”defineIdFamily()
Section titled “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, own-key counts, and prefix uniqueness must satisfy the accepted Cairn invariants before any codec is returned.
Type Parameters
Section titled “Type Parameters”F extends string
Literal identifier-family name.
D extends Readonly<Record<string, Readonly<{ prefix: string;
}>>>
Literal own kind declarations for the family.
Parameters
Section titled “Parameters”definition
Section titled “definition”Readonly<{ family: F; version: 1; kinds: D; }>
Trusted version 1 family declaration to validate.
Returns
Section titled “Returns”IdFamily<F, D>
One readonly codec property for every own kind key.
Throws
Section titled “Throws”CairnDefinitionError When any declaration invariant or property access fails.
References
Section titled “References”identifierCandidateSchema
Section titled “identifierCandidateSchema”Re-exports identifierCandidateSchema
identifierDefinitionSchema
Section titled “identifierDefinitionSchema”Re-exports identifierDefinitionSchema