edinburgh 0.1.3 → 0.3.0

package/build/src/types.d.ts

@@ -1,15 +1,16 @@
-import { Bytes } from "./bytes.js";
+import { DataPack } from "./datapack.js";
+import * as olmdb from "olmdb";
 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.
- */
+* @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;
@@ -17,95 +18,51 @@ export declare abstract class TypeWrapper<const T> {
     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;
+    * Serialize a value from an object property to a Pack.
+    * @param value - The value to serialize.
+    * @param pack - The Pack instance to write to.
+    */
+    abstract serialize(value: T, pack: DataPack): 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[];
+    * Deserialize a value from a Pack into an object property.
+    * @param pack - The Pack instance to read from.
+    */
+    abstract deserialize(pack: DataPack): T;
     /**
-     * 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;
+    * Validate a value.
+    * @param value - The value to validate.
+    * @returns - A DatabaseError if validation fails.
+    */
+    abstract getError(value: T): DatabaseError | void;
     /**
-     * Serialize type metadata to bytes (for schema serialization).
-     * @param bytes - The Bytes instance to write to.
-     */
-    serializeType(bytes: Bytes): void;
+    * Serialize type metadata to a Pack (for schema serialization).
+    * @param pack - The Pack instance to write to.
+    */
+    serializeType(pack: DataPack): 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;
+    * 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.
+    */
+    containsNull(value: T): boolean;
     toString(): string;
+    clone(value: T): T;
+    equals(value1: T, value2: T): boolean;
 }
-/**
- * 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.
-     */
+    * 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[]> {
+* @internal Type wrapper for array values with optional length constraints.
+* @template T - The type of array elements.
+*/
+export declare class SetType<T> extends TypeWrapper<Set<T>> {
     inner: TypeWrapper<T>;
     opts: {
         min?: number;
@@ -113,189 +70,164 @@ declare class ArrayType<T> extends TypeWrapper<T[]> {
     };
     kind: string;
     /**
-     * Create a new ArrayType.
-     * @param inner - Type wrapper for array elements.
-     * @param opts - Array constraints (min/max length).
-     */
+    * Create a new SetType.
+    * @param inner - Type wrapper for set elements.
+    */
     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>;
+    serialize(value: Set<T>, pack: DataPack): void;
+    deserialize(pack: DataPack): Set<T>;
+    getError(value: Set<T>): olmdb.DatabaseError | undefined;
+    serializeType(pack: DataPack): void;
+    static deserializeType(pack: DataPack, featureFlags: number): SetType<any>;
+    default(): Set<T>;
+    clone(value: Set<T>): Set<T>;
+    equals(a: Set<T>, b: Set<T>): boolean;
 }
 /**
- * @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>> {
+* @internal Type wrapper for model relationships (foreign keys).
+* @template T - The target model class type.
+*/
+export declare class LinkType<T extends typeof Model<unknown>> extends TypeWrapper<InstanceType<T>> {
     kind: string;
     TargetModel: T;
     /**
-     * Create a new LinkType.
-     * @param TargetModel - The model class this link points to.
-     */
+    * 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>;
+    serialize(model: InstanceType<T>, pack: DataPack): void;
+    deserialize(pack: DataPack): any;
+    getError(value: InstanceType<T>): olmdb.DatabaseError | undefined;
+    serializeType(pack: DataPack): void;
+    static deserializeType(pack: DataPack, 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});
- * ```
- */
+/** Type wrapper instance for the string type. */
+export declare const string: TypeWrapper<string>;
+/** Type wrapper instance for the ordered string type, which is just like a string
+ * except that it sorts lexicographically in the database (instead of by incrementing
+ * length first), making it suitable for index fields that want lexicographic range
+ * scans. Ordered strings are implemented as null-terminated UTF-8 strings, so they
+ * may not contain null characters.
+ */
+export declare const orderedString: TypeWrapper<string>;
+/** Type wrapper instance for the number type. */
+export declare const number: TypeWrapper<number>;
+/** Type wrapper instance for the date/time type. */
+export declare const dateTime: TypeWrapper<Date>;
+/** Type wrapper instance for the boolean type. */
+export declare const boolean: TypeWrapper<boolean>;
+/** Type wrapper instance for the identifier type. */
+export declare const identifier: TypeWrapper<string>;
+/** Type wrapper instance for the 'undefined' type. */
+export declare const undef: TypeWrapper<undefined>;
+/**
+* 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): TypeWrapper<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): TypeWrapper<UnwrapTypes<T>>;
+/**
+* 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): TypeWrapper<UnwrapTypes<[T, typeof undef]>>;
+/**
+* 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[]> = {
+}): TypeWrapper<T[]>;
+/**
+* Create a Set type wrapper with optional length constraints.
+* @template T - The element type.
+* @param inner - Type wrapper for set elements.
+* @param opts - Optional constraints (min/max length).
+* @returns A set type instance.
+*
+* @example
+* ```typescript
+* const stringSet = E.set(E.string);
+* const boundedSet = E.set(E.number, {min: 1, max: 10});
+* ```
+*/
+export declare function set<const T>(inner: TypeWrapper<T>, opts?: {
+    min?: number;
+    max?: number;
+}): TypeWrapper<Set<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): TypeWrapper<InstanceType<T>>;
+export type BasicType = string | number | boolean | undefined | null;
+export type UnwrapTypes<T extends (TypeWrapper<unknown> | 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 {};
+* Serialize a type wrapper to a Pack for schema persistence.
+* @param arg - The type wrapper to serialize.
+* @param pack - The Pack instance to write to.
+*/
+export declare function serializeType(arg: TypeWrapper<any>, pack: DataPack): void;
+/**
+* Deserialize a type wrapper from a Pack.
+* @param pack - The Pack instance to read from.
+* @param featureFlags - Feature flags for version compatibility.
+* @returns The deserialized type wrapper.
+*/
+export declare function deserializeType(pack: DataPack, featureFlags: number): TypeWrapper<any>;