identifier

Import

Import

import * as api from "@fungi.computer/cairn/id";

Exports

Kind	Export	Description
Cclass	CairnDefinitionError	Bounded error thrown when a trusted family declaration violates Cairn’s version 1 definition invariants.
Cclass	CairnGenerationError	Bounded error thrown when secure entropy is unavailable during codec generation.
Ttype alias	CairnId	Canonical opaque identifier branded by its declaring family, kind, and wire grammar version.
Ttype alias	IdOf	Extracts the distinctly branded identifier produced by an ID codec.
Ttype alias	IdParseError	Bounded public description of a rejected identifier value.
Ttype alias	IdParseResult	Successful canonical parsing or one bounded parse error.
Ttype alias	IdCodec	Generator and canonical parser for one declared identifier family and kind.
Ttype alias	IdKindDefinition	Trusted declaration for one identifier kind within a family.
Ttype alias	IdFamily	Readonly family whose every own kind key maps to one distinctly branded version 1 codec.
fnfunction	defineIdFamily()	Validates one trusted version 1 family declaration and creates its readonly family-scoped codecs.

CairnDefinitionErrorCclass

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

Signature

new CairnDefinitionError(): CairnDefinitionError;

Creates a fresh bounded family-definition error.

Returns

CairnDefinitionError

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "CairnDefinitionError" = "CairnDefinitionError";

Stable public error name.

Overrides

Signature

Error.name;

code

Signature

readonly code: "invalid_definition" = "invalid_definition";

Stable machine-readable error discriminator.

---

CairnGenerationErrorCclass

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

Signature

new CairnGenerationError(input): CairnGenerationError;

Creates a fresh bounded generation error.

Parameters

Parameter	Type	Description
input	Readonly<{ family: string; kind: string; }>	Validated family and kind metadata for the failing codec.

Returns

CairnGenerationError

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "CairnGenerationError" = "CairnGenerationError";

Stable public error name.

Overrides

Signature

Error.name;

code

Signature

readonly code: "entropy_unavailable" = "entropy_unavailable";

Stable machine-readable error discriminator.

family

Signature

readonly family: string;

Validated family whose codec could not generate an identifier.

kind

Signature

readonly kind: string;

Validated kind whose codec could not generate an identifier.

version

Signature

readonly version: 1 = 1;

Wire grammar version used by the codec.

CairnIdTtype alias

Signature

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

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

Type Declaration

Name	Type	Description
[cairnIdBrand]	readonly [F, K, V]	Compile-time identity metadata that is never serialized.

Type Parameters

Type Parameter	Default type	Description
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.

---

IdOfTtype alias

Signature

type 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

Type Parameter	Description
C	Codec whose identifier type is required.

---

IdParseErrorTtype alias

Signature

type 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

Type Parameter	Description
F extends string	Declaring identifier family.
K extends string	Identifier kind within the family.

---

IdParseResultTtype alias

Signature

type 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

Type Parameter	Description
I	Branded identifier returned after successful parsing.
F extends string	Declaring identifier family.
K extends string	Identifier kind within the family.

---

IdCodecTtype alias

Signature

type IdCodec<F, K, V> = object;

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

Type Parameters

Type Parameter	Default type	Description
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

family

Signature

readonly family: F;

Declared identifier family; it is not serialized into metadata.

kind

Signature

readonly kind: K;

Declared identifier kind; it is not serialized into metadata.

version

Signature

readonly version: V;

Wire grammar version implemented by this codec.

schema

Signature

readonly schema: z.ZodType<CairnId<F, K, V>, string>;

Schema for the untrusted wire boundary; outputs this codec’s branded ID.

Methods

generate()

Signature

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()

Signature

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

Parses a decoded string candidate without trimming, decoding, or normalization.

Parameters

Parameter	Type	Description
value	string	Decoded string candidate.

Returns

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

The original branded value or one bounded parse error.

is()

Signature

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

Reports whether a decoded string candidate is canonical for this codec.

Parameters

Parameter	Type	Description
value	string	Decoded string candidate.

Returns

value is CairnId<F, K, V>

Whether the value is accepted by IdCodec.parse.

---

IdKindDefinitionTtype alias

Signature

type IdKindDefinition = Readonly<{
  prefix: string;
}>;

Trusted declaration for one identifier kind within a family.

---

IdFamilyTtype alias

Signature

type 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

Type Parameter	Description
F extends string	Declaring identifier family.
D extends Readonly<Record<string, IdKindDefinition>>	Own identifier-kind declarations for the family.

defineIdFamily()fnfunction

Signature

function 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

Type Parameter	Description
F extends string	Literal identifier-family name.
D extends Readonly<Record<string, Readonly<{ prefix: string; }>>>	Literal own kind declarations for the family.

Parameters

Parameter	Type	Description
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.

References

identifierCandidateSchema

Re-exports identifierCandidateSchema

---

identifierDefinitionSchema

Re-exports identifierDefinitionSchema