edinburgh 0.1.2

package/build/src/types.d.ts

@@ -0,0 +1,301 @@
+import { Bytes } from "./bytes.js";
+import { DatabaseError } from "olmdb";
+import { Model } from "./models.js";
+/**
+ * @internal Abstract base class for all type wrappers in the Edinburgh ORM system.
+ *
+ * This is an implementation detail and should not be referenced directly in user code.
+ * Type wrappers define how values are serialized to/from the database and how they are validated.
+ * Each type wrapper must implement serialization, deserialization, and validation logic.
+ *
+ * @template T - The TypeScript type this wrapper represents.
+ */
+export declare abstract class TypeWrapper<const T> {
+    /** @internal Used for TypeScript type inference - this field is required for the type system */
+    _T: T;
+    /** A string identifier for this type, used during serialization */
+    abstract kind: string;
+    constructor();
+    /**
+     * Serialize a value from an object property to bytes.
+     * @param obj - The object containing the value.
+     * @param prop - The property name or index.
+     * @param bytes - The Bytes instance to write to.
+     * @param model - Optional model instance for context.
+     */
+    abstract serialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    /**
+     * Deserialize a value from bytes into an object property.
+     * @param obj - The object to set the value on.
+     * @param prop - The property name or index.
+     * @param bytes - The Bytes instance to read from.
+     * @param model - Optional model instance for context.
+     */
+    abstract deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    /**
+     * Validate a value and return any validation errors.
+     * @param obj - The object containing the value.
+     * @param prop - The property name or index.
+     * @returns Array of validation errors (empty if valid).
+     */
+    abstract getErrors(obj: any, prop: string | number): DatabaseError[];
+    /**
+     * Validate a value and serialize it, throwing on validation errors.
+     * @param obj - The object containing the value.
+     * @param prop - The property name or index.
+     * @param bytes - The Bytes instance to write to.
+     * @param model - Optional model instance for context.
+     * @throws {DatabaseError} If validation fails.
+     */
+    validateAndSerialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    /**
+     * Serialize type metadata to bytes (for schema serialization).
+     * @param bytes - The Bytes instance to write to.
+     */
+    serializeType(bytes: Bytes): void;
+    /**
+     * Check if indexing should be skipped for this field value.
+     * @param obj - The object containing the value.
+     * @param prop - The property name or index.
+     * @returns true if indexing should be skipped.
+     */
+    checkSkipIndex(obj: any, prop: string | number): boolean;
+    toString(): string;
+}
+/**
+ * Optional interface for type wrappers that can provide default values.
+ * @template T - The TypeScript type this wrapper represents.
+ */
+export interface TypeWrapper<T> {
+    /**
+     * Generate a default value for this type.
+     * @param model - The model instance.
+     * @returns The default value.
+     */
+    default?(model: any): T;
+}
+/**
+ * @internal Type wrapper for string values.
+ */
+declare class StringType extends TypeWrapper<string> {
+    kind: string;
+    serialize(obj: any, prop: string, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+}
+/**
+ * @internal Type wrapper for number values.
+ */
+declare class NumberType extends TypeWrapper<number> {
+    kind: string;
+    serialize(obj: any, prop: string, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+}
+/**
+ * @internal Type wrapper for boolean values.
+ */
+declare class BooleanType extends TypeWrapper<boolean> {
+    kind: string;
+    serialize(obj: any, prop: string, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+}
+/**
+ * @internal Type wrapper for array values with optional length constraints.
+ * @template T - The type of array elements.
+ */
+declare class ArrayType<T> extends TypeWrapper<T[]> {
+    inner: TypeWrapper<T>;
+    opts: {
+        min?: number;
+        max?: number;
+    };
+    kind: string;
+    /**
+     * Create a new ArrayType.
+     * @param inner - Type wrapper for array elements.
+     * @param opts - Array constraints (min/max length).
+     */
+    constructor(inner: TypeWrapper<T>, opts?: {
+        min?: number;
+        max?: number;
+    });
+    serialize(obj: any, prop: string, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+    serializeType(bytes: Bytes): void;
+    static deserializeType(bytes: Bytes, featureFlags: number): ArrayType<any>;
+}
+/**
+ * @internal Type wrapper for union/discriminated union types.
+ * @template T - The union type this wrapper represents.
+ */
+declare class OrType<const T> extends TypeWrapper<T> {
+    choices: TypeWrapper<T>[];
+    kind: string;
+    /**
+     * Create a new OrType.
+     * @param choices - Array of type wrappers representing the union choices.
+     */
+    constructor(choices: TypeWrapper<T>[]);
+    _getChoiceIndex(obj: any, prop: string | number): number;
+    serialize(obj: any, prop: string, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+    checkSkipIndex(obj: any, prop: string | number): boolean;
+    serializeType(bytes: Bytes): void;
+    static deserializeType(bytes: Bytes, featureFlags: number): OrType<any>;
+}
+/**
+ * @internal Type wrapper for literal values (constants).
+ * @template T - The literal type this wrapper represents.
+ */
+declare class LiteralType<const T> extends TypeWrapper<T> {
+    value: T;
+    kind: string;
+    /**
+     * Create a new LiteralType.
+     * @param value - The literal value this type represents.
+     */
+    constructor(value: T);
+    serialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes, model?: any): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+    serializeType(bytes: Bytes): void;
+    checkSkipIndex(obj: any, prop: string | number): boolean;
+    static deserializeType(bytes: Bytes, featureFlags: number): LiteralType<any>;
+    default(model: any): T;
+}
+/**
+ * @internal Type wrapper for auto-generated unique identifier strings.
+ */
+declare class IdentifierType extends TypeWrapper<string> {
+    kind: string;
+    serialize(obj: any, prop: string | number, bytes: Bytes): void;
+    deserialize(obj: any, prop: string | number, bytes: Bytes): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+    serializeType(bytes: Bytes): void;
+    static deserializeType(bytes: Bytes, featureFlags: number): IdentifierType;
+    default(model: Model<any>): string;
+}
+/**
+ * @internal Type wrapper for model relationships (foreign keys).
+ * @template T - The target model class type.
+ */
+export declare class LinkType<T extends typeof Model<any>> extends TypeWrapper<InstanceType<T>> {
+    kind: string;
+    TargetModel: T;
+    /**
+     * Create a new LinkType.
+     * @param TargetModel - The model class this link points to.
+     */
+    constructor(TargetModel: T);
+    serialize(obj: any, prop: string | number, bytes: Bytes, model: Model<InstanceType<T>>): void;
+    deserialize(obj: any, prop: string, bytes: Bytes, sourceModel: Model<unknown>): void;
+    getErrors(obj: any, prop: string | number): DatabaseError[];
+    serializeType(bytes: Bytes): void;
+    static deserializeType(bytes: Bytes, featureFlags: number): LinkType<any>;
+}
+/** Constant representing the string type. */
+export declare const string: StringType;
+/** Constant representing the number type. */
+export declare const number: NumberType;
+/** Constant representing the boolean type. */
+export declare const boolean: BooleanType;
+/** Constant representing the identifier type. */
+export declare const identifier: IdentifierType;
+/**
+ * Create a literal type wrapper for a constant value.
+ * @template T - The literal type.
+ * @param value - The literal value.
+ * @returns A literal type instance.
+ *
+ * @example
+ * ```typescript
+ * const statusType = E.literal("active");
+ * const countType = E.literal(42);
+ * ```
+ */
+export declare function literal<const T>(value: T): LiteralType<T>;
+/**
+ * Create a union type wrapper from multiple type choices.
+ * @template T - Array of type wrapper or basic types.
+ * @param choices - The type choices for the union.
+ * @returns A union type instance.
+ *
+ * @example
+ * ```typescript
+ * const stringOrNumber = E.or(E.string, E.number);
+ * const status = E.or("active", "inactive", "pending");
+ * ```
+ */
+export declare function or<const T extends (TypeWrapper<unknown> | BasicType)[]>(...choices: T): OrType<UnwrapTypes<T>>;
+/** Constant representing the 'undefined' type. */
+export declare const undef: LiteralType<undefined>;
+/**
+ * Create an optional type wrapper (allows undefined).
+ * @template T - Type wrapper or basic type to make optional.
+ * @param inner - The inner type to make optional.
+ * @returns A union type that accepts the inner type or undefined.
+ *
+ * @example
+ * ```typescript
+ * const optionalString = E.opt(E.string);
+ * const optionalNumber = E.opt(E.number);
+ * ```
+ */
+export declare function opt<const T extends TypeWrapper<unknown> | BasicType>(inner: T): OrType<(T extends TypeWrapper<infer U> ? U : T) | undefined>;
+/**
+ * Create an array type wrapper with optional length constraints.
+ * @template T - The element type.
+ * @param inner - Type wrapper for array elements.
+ * @param opts - Optional constraints (min/max length).
+ * @returns An array type instance.
+ *
+ * @example
+ * ```typescript
+ * const stringArray = E.array(E.string);
+ * const boundedArray = E.array(E.number, {min: 1, max: 10});
+ * ```
+ */
+export declare function array<const T>(inner: TypeWrapper<T>, opts?: {
+    min?: number;
+    max?: number;
+}): ArrayType<T>;
+/**
+ * Create a link type wrapper for model relationships.
+ * @template T - The target model class.
+ * @param TargetModel - The model class this link points to.
+ * @returns A link type instance.
+ *
+ * @example
+ * ```typescript
+ * class User extends E.Model<User> {
+ *   posts = E.field(E.array(E.link(Post, 'author')));
+ * }
+ *
+ * class Post extends E.Model<Post> {
+ *   author = E.field(E.link(User));
+ * }
+ * ```
+ */
+export declare function link<const T extends typeof Model<any>>(TargetModel: T): LinkType<T>;
+export type BasicType = TypeWrapper<any> | string | number | boolean | undefined | null;
+export type UnwrapTypes<T extends BasicType[]> = {
+    [K in keyof T]: T[K] extends TypeWrapper<infer U> ? U : T[K];
+}[number];
+/**
+ * Serialize a type wrapper to bytes for schema persistence.
+ * @param arg - The type wrapper to serialize.
+ * @param bytes - The Bytes instance to write to.
+ */
+export declare function serializeType(arg: TypeWrapper<any>, bytes: Bytes): void;
+/**
+ * Deserialize a type wrapper from bytes.
+ * @param bytes - The Bytes instance to read from.
+ * @param featureFlags - Feature flags for version compatibility.
+ * @returns The deserialized type wrapper.
+ */
+export declare function deserializeType(bytes: Bytes, featureFlags: number): TypeWrapper<any>;
+export {};