domain-objects/dist/instantiation/Ref.d.ts

A simple, convenient way to represent domain objects, leverage domain knowledge, and add runtime validation in your code base.

/** biome-ignore-all lint/suspicious/noExplicitAny: in this file, we depend on `any` to make it generic enough to reuse */
import type { Ref as RefType } from '../reference/Ref.type';
import type { DomainObjectShape, Refable } from '../reference/Refable';
/**
 * In Domain Driven Design, a Reference is a special type of Domain Literal that represents a reference to another Domain Object.
 *
 * A Domain Reference:
 * - contains only the identifying properties of the referenced object
 * - is immutable (like all Domain Literals)
 * - is used to refer to Domain Entities or Domain Events without including their full data
 *
 * The purpose of a Domain Reference is to enable lightweight references between domain objects without circular dependencies or data duplication.
 *
 * For example:
 * - A `SeaTurtleRef { uuid: string }` is a reference to a SeaTurtle by its primary key
 * - A `SeaTurtleRef { seawaterSecurityNumber: string }` is a reference to a SeaTurtle by its unique key
 *
 * Note:
 * - `Ref` is a flexible reference type that accepts either primary or unique key references
 * - Use `RefByPrimary` or `RefByUnique` when you need to be specific about the reference type
 */
export type Ref<TDobj extends Refable<TShape, TPrimary, TUnique>, TShape extends DomainObjectShape = any, // todo: update DomainObjectShape -> DomainReferenceableInstance to enable extraction of primary and unique keys via types, when typescript supports constructor inference from instances
TPrimary extends readonly string[] = any, TUnique extends readonly string[] = any> = RefType<TDobj, TShape, TPrimary, TUnique>;
export declare const Ref: {
    new <TDobj extends Refable<TShape, TPrimary, TUnique>, TShape extends DomainObjectShape = any, TPrimary extends readonly string[] = any, TUnique extends readonly string[] = any>(props: Ref<TDobj, TShape, TPrimary, TUnique>): Ref<TDobj, TShape, TPrimary, TUnique>;
    /**
     * .what = an interface via which to construct instances w/ immute operations
     *
     * .why =
     *   - immute operations such as .clone produce more maintainable code by preventing unexpected mutations
     *   - these immute operations provide a safe pit of success for common operations
     */
    build<TDobj extends Refable<TShape, TPrimary, TUnique>, TShape extends DomainObjectShape = any, TPrimary extends readonly string[] = any, TUnique extends readonly string[] = any>(props: Ref<TDobj, TShape, TPrimary, TUnique>): Ref<TDobj, TShape, TPrimary, TUnique>;
    /**
     * .what = an interface via which to construct instances w/ immute operations
     *
     * .why =
     *   - immute operations such as .clone produce more maintainable code by preventing unexpected mutations
     *   - these immute operations provide a safe pit of success for common operations
     */
    as<TDobj extends Refable<TShape, TPrimary, TUnique>, TShape extends DomainObjectShape = any, TPrimary extends readonly string[] = any, TUnique extends readonly string[] = any>(props: Ref<TDobj, TShape, TPrimary, TUnique>): Ref<TDobj, TShape, TPrimary, TUnique>;
};