Serialization API reference

import type { Serializable } from './Serializable.js';
import { SerializationRegistry } from './SerializationRegistry.js';
import { type SerializedValueEnvelope } from './contracts/index.js';
import type * as serialization from './contracts/index.js';
/**
 * Serializes one registered root constructor using JSON state plus model refs.
 *
 * @example
 * const payload = app().serializer.serialize(job);
 * const restored = await app().serializer.deserialize(
 * 	JSON.parse(JSON.stringify(payload)),
 * );
 */
export declare class Serializer implements serialization.SerializerService {
    #private;
    readonly registry: SerializationRegistry;
    /**
     * Creates an application-scoped serializer.
     *
     * @param options - Registered root classes and ActiveRecord models.
     */
    constructor(options?: serialization.SerializerOptions);
    /**
     * Serializes one registered root object.
     *
     * @param value - Object whose `toJSON()` result matches its constructor input.
     * @returns Versioned JSON-safe envelope.
     */
    serialize(value: Serializable): SerializedValueEnvelope;
    /**
     * Restores one validated serializer envelope.
     *
     * @param payload - Unknown durable payload.
     * @returns Reconstructed registered root object.
     */
    deserialize<TInstance extends Serializable = Serializable>(payload: unknown): Promise<TInstance>;
}

import { ActiveRecord, type ActiveRecordClass } from '../db/index.js';
import type { Serializable } from './Serializable.js';
import type * as serialization from './contracts/index.js';
/**
 * Application-scoped allowlist for serializable roots and ActiveRecord models.
 *
 * Payloads contain only stable names. Resolution always uses an exact instance
 * prototype, so an unregistered subclass cannot inherit a durable identity.
 */
export declare class SerializationRegistry {
    #private;
    /**
     * Creates a registry from application serializer options.
     *
     * @param options - Initial root classes and ActiveRecord models.
     */
    constructor(options?: Pick<serialization.SerializerOptions, 'classes' | 'models'>);
    /**
     * Registers a stable root-class name.
     *
     * @param name - Durable class key.
     * @param Class - Constructor accepting the state returned by `toJSON()`.
     * @returns This registry.
     */
    registerClass(name: string, Class: serialization.SerializableClass): this;
    /**
     * Registers a stable ActiveRecord model name.
     *
     * @param name - Durable model key.
     * @param Model - Concrete ActiveRecord model.
     * @returns This registry.
     */
    registerModel(name: string, Model: ActiveRecordClass): this;
    /**
     * Returns the stable name for a serializable instance's exact prototype.
     *
     * @param value - Root instance to resolve.
     * @returns Registered name, or null.
     */
    nameForSerializable(value: Serializable): string | null;
    /**
     * Returns the registered class for a serializable instance.
     *
     * @param value - Root instance to resolve.
     * @returns Registered constructor, or null.
     */
    classForSerializable(value: Serializable): serialization.SerializableClass | null;
    /**
     * Resolves a root class by its durable name.
     *
     * @param name - Durable class name.
     * @returns Registered constructor, or null.
     */
    classForName(name: string): serialization.SerializableClass | null;
    /**
     * Returns the registered model for a record instance.
     *
     * @param record - ActiveRecord instance to resolve.
     * @returns Registered model, or null.
     */
    modelForRecord(record: ActiveRecord): ActiveRecordClass | null;
    /**
     * Returns the stable name for an exact ActiveRecord model.
     *
     * @param Model - Model constructor to resolve.
     * @returns Registered name, or null.
     */
    nameForModel(Model: ActiveRecordClass): string | null;
    /**
     * Resolves an ActiveRecord model by its durable name.
     *
     * @param name - Durable model name.
     * @returns Registered model, or null.
     */
    modelForName(name: string): ActiveRecordClass | null;
}

/**
 * Constructor-backed object that exposes its complete durable state.
 *
 * The returned state must contain only JSON values and registered
 * ActiveRecord instances. Deserialization passes the restored state back to
 * the registered class constructor.
 *
 * @template TState - Complete state accepted by the concrete class constructor.
 */
export interface Serializable<TState = unknown> {
    /**
     * Returns the complete state needed to reconstruct this object.
     *
     * @returns Constructor state containing JSON values and registered records.
     */
    toJSON(): TState;
}

import type { Serializable } from '../Serializable.js';
/**
 * Constructor for a registered object whose complete runtime state is exposed
 * through `toJSON()`.
 *
 * @template TState - Complete constructor state owned by the class.
 * @template TInstance - Concrete serializable instance.
 */
export interface SerializableClass<TState = any, TInstance extends Serializable<TState> = Serializable<TState>> {
    /** Runtime class name used only for diagnostics. */
    readonly name: string;
    /** Exact instance prototype associated with this constructor. */
    readonly prototype: TInstance;
    /**
     * Reconstructs an instance from fully restored constructor state.
     *
     * @param state - State previously returned by the instance's `toJSON()` method.
     */
    new (state: TState): TInstance;
}

import type { ActiveRecordClass } from '../../db/index.js';
import type { SerializableClass } from './SerializableClass.js';
/**
 * Framework serializer configuration supplied when creating an application.
 */
export interface SerializerOptions {
    /**
     * Stable class keys mapped to constructors that accept their `toJSON()` state.
     */
    classes?: Record<string, SerializableClass>;
    /**
     * ActiveRecord models available for identity-based restoration.
     *
     * Explicit stable keys keep durable payloads independent of table names.
     */
    models?: Record<string, ActiveRecordClass>;
}

/**
 * Stable marker identifying framework serializer payloads.
 */
export declare const SERIALIZED_VALUE_FORMAT: "platform.serialized-object";
/**
 * Current framework serializer wire-format version.
 */
export declare const SERIALIZED_VALUE_VERSION: 1;
/**
 * Reserved object key used only for framework-owned serialized references.
 *
 * Application constructor state cannot use this key because it would be
 * ambiguous with framework metadata during restoration.
 */
export declare const SERIALIZED_REFERENCE_KEY: "$platform";
/**
 * Marker value identifying one serialized ActiveRecord reference.
 */
export declare const SERIALIZED_ACTIVE_RECORD_TYPE: "active-record";
/**
 * Primitive values supported by ordinary JSON without coercion.
 */
export type SerializedPrimitive = null | string | boolean | number;
/**
 * Registered ActiveRecord identity stored inside otherwise ordinary JSON.
 */
export interface SerializedActiveRecordReference {
    /** Reserved framework reference discriminator. */
    [SERIALIZED_REFERENCE_KEY]: typeof SERIALIZED_ACTIVE_RECORD_TYPE;
    /** Stable application-registered model key. */
    model: string;
    /** JSON-safe logical primary-key value. */
    id: string | number;
}
/**
 * Plain serialized object containing application-owned constructor state.
 */
export interface SerializedObject {
    [key: string]: SerializedValue;
}
/**
 * JSON value supported inside serialized constructor state.
 *
 * ActiveRecord references are the only framework-specific extension.
 */
export type SerializedValue = SerializedPrimitive | SerializedValue[] | SerializedObject | SerializedActiveRecordReference;
/**
 * Versioned root-class envelope produced by `Serializer.serialize()`.
 */
export interface SerializedValueEnvelope extends Record<string, unknown> {
    /** Stable framework serializer format marker. */
    format: typeof SERIALIZED_VALUE_FORMAT;
    /** Wire-format version used to interpret the constructor state. */
    version: typeof SERIALIZED_VALUE_VERSION;
    /** Stable registry key for the root application class. */
    name: string;
    /** Serialized constructor state for the registered root class. */
    state: SerializedValue;
}

/**
 * Serializer operation that rejected a runtime or durable value.
 */
export type SerializationOperation = 'serialize' | 'deserialize';
/**
 * Stable failure categories exposed by SerializationError.
 */
export type SerializationErrorCode = 'unsupported_type' | 'invalid_value' | 'circular_reference' | 'unregistered_class' | 'unregistered_model' | 'unsaved_active_record' | 'dirty_active_record' | 'trashed_active_record' | 'active_record_not_found' | 'active_record_restore_failed' | 'invalid_payload' | 'unsupported_version' | 'class_construction_failed';
/**
 * Structured details used to create a safe serializer failure.
 */
export interface SerializationErrorOptions {
    /** Operation that raised the failure. */
    operation: SerializationOperation;
    /** Stable machine-readable failure category. */
    code: SerializationErrorCode;
    /** JSONPath-like location of the rejected value. */
    path: string;
    /** Safe explanation that does not stringify the rejected value. */
    message: string;
    /** Lower-level error retained for diagnostics. */
    cause?: unknown;
}
/**
 * Error raised when runtime state cannot be serialized or restored losslessly.
 */
export declare class SerializationError extends Error {
    /** Operation that raised this error. */
    readonly operation: SerializationOperation;
    /** Stable machine-readable failure category. */
    readonly code: SerializationErrorCode;
    /** JSONPath-like location of the rejected value. */
    readonly path: string;
    /**
     * Creates one path-aware serializer failure.
     *
     * @param options - Safe structured failure details.
     */
    constructor(options: SerializationErrorOptions);
}

/**
 * Registry entry category involved in a registration failure.
 */
export type SerializationRegistryEntryType = 'class' | 'model';
/**
 * Error raised when an application configures an invalid or ambiguous
 * serialization registry entry.
 */
export declare class SerializationRegistryError extends Error {
    readonly entryType: SerializationRegistryEntryType;
    /**
     * Creates a serializer registry configuration failure.
     *
     * @param entryType - Registry category being configured.
     * @param message - Safe explanation of the invalid registration.
     */
    constructor(entryType: SerializationRegistryEntryType, message: string);
}