@korajs/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,401 @@
+import { R as RandomSource, F as FieldKind, a as FieldDescriptor, C as CustomResolver, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, d as Operation, V as VersionVector } from './events-D_kDPDC9.js';
+export { e as CONNECTION_QUALITIES, f as ConnectionQuality, g as Constraint, H as HLCTimestamp, h as HybridLogicalClock, K as KoraEvent, i as KoraEventByType, j as KoraEventEmitter, k as KoraEventListener, l as KoraEventType, M as MERGE_STRATEGIES, m as MergeStrategy, n as MergeTrace, o as OnDeleteAction, p as OperationInput, q as RelationType, T as TimeSource, r as createOperation, s as isValidOperation, v as verifyOperationIntegrity } from './events-D_kDPDC9.js';
+
+/**
+ * Base error class for all Kora errors.
+ * Every error includes a machine-readable code and optional context for debugging.
+ */
+declare class KoraError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when schema validation fails during defineSchema() or at app initialization.
+ */
+declare class SchemaValidationError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when an operation is invalid or cannot be created.
+ */
+declare class OperationError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when a merge conflict cannot be automatically resolved.
+ */
+declare class MergeConflictError extends KoraError {
+    readonly operationA: {
+        id: string;
+        collection: string;
+    };
+    readonly operationB: {
+        id: string;
+        collection: string;
+    };
+    readonly field: string;
+    constructor(operationA: {
+        id: string;
+        collection: string;
+    }, operationB: {
+        id: string;
+        collection: string;
+    }, field: string);
+}
+/**
+ * Thrown when a sync error occurs.
+ */
+declare class SyncError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when a storage operation fails.
+ */
+declare class StorageError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when the HLC detects excessive clock drift.
+ * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
+ */
+declare class ClockDriftError extends KoraError {
+    readonly currentHlcTime: number;
+    readonly physicalTime: number;
+    constructor(currentHlcTime: number, physicalTime: number);
+}
+
+/**
+ * Generates a UUID v7 per RFC 9562.
+ * UUID v7 encodes a Unix timestamp in milliseconds in the most significant 48 bits,
+ * making UUIDs time-sortable while remaining globally unique.
+ *
+ * @param timestamp - Unix timestamp in milliseconds (defaults to Date.now())
+ * @param randomSource - Injectable random source for deterministic testing
+ * @returns A UUID v7 string in standard 8-4-4-4-12 format
+ *
+ * @example
+ * ```typescript
+ * const id = generateUUIDv7()
+ * // "018f3a5c-7e00-7123-abcd-1234567890ab"
+ * ```
+ */
+declare function generateUUIDv7(timestamp?: number, randomSource?: RandomSource): string;
+/**
+ * Extracts the Unix timestamp in milliseconds from a UUID v7.
+ *
+ * @param uuid - A UUID v7 string
+ * @returns The encoded Unix timestamp in milliseconds
+ */
+declare function extractTimestamp(uuid: string): number;
+/**
+ * Validates whether a string is a valid UUID v7.
+ * Checks format, version (7), and variant (10xx).
+ *
+ * @param uuid - String to validate
+ * @returns true if the string is a valid UUID v7
+ */
+declare function isValidUUIDv7(uuid: string): boolean;
+
+/**
+ * Base field builder implementing the builder pattern for schema field definitions.
+ * Each builder is immutable — modifier methods return new builder instances.
+ *
+ * Type parameters track field metadata at the type level for inference:
+ * - Kind: the field kind ('string', 'number', etc.)
+ * - Req: whether the field is required (true = required on insert)
+ * - Auto: whether the field is auto-populated (true = excluded from insert input)
+ *
+ * @example
+ * ```typescript
+ * t.string()                    // required string field
+ * t.string().optional()         // optional string field
+ * t.string().default('hello')   // string with default value
+ * t.timestamp().auto()          // auto-populated timestamp
+ * ```
+ */
+declare class FieldBuilder<Kind extends FieldKind = FieldKind, Req extends boolean = true, Auto extends boolean = false> {
+    protected readonly _kind: Kind;
+    protected readonly _required: boolean;
+    protected readonly _defaultValue: unknown;
+    protected readonly _auto: boolean;
+    constructor(kind: Kind, required?: Req, defaultValue?: unknown, auto?: Auto);
+    /** Mark this field as optional (not required on insert) */
+    optional(): FieldBuilder<Kind, false, Auto>;
+    /** Set a default value for this field. Implicitly makes the field optional. */
+    default(value: unknown): FieldBuilder<Kind, false, Auto>;
+    /** Mark this field as auto-populated (e.g., createdAt timestamps). Developers cannot set auto fields. */
+    auto(): FieldBuilder<Kind, false, true>;
+    /** @internal Build the final FieldDescriptor. Used by defineSchema(). */
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for enum fields with constrained string values.
+ * Preserves the literal enum tuple type for inference.
+ */
+declare class EnumFieldBuilder<Values extends readonly string[] = readonly string[], Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'enum', Req, Auto> {
+    private readonly _enumValues;
+    constructor(values: Values, required?: Req, defaultValue?: unknown, auto?: Auto);
+    optional(): EnumFieldBuilder<Values, false, Auto>;
+    default(value: Values[number]): EnumFieldBuilder<Values, false, Auto>;
+    auto(): EnumFieldBuilder<Values, false, true>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for array fields with a typed item kind.
+ * Preserves the item kind type parameter for inference.
+ */
+declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'array', Req, Auto> {
+    private readonly _itemKind;
+    constructor(itemBuilder: FieldBuilder<ItemKind>, required?: Req, defaultValue?: unknown, auto?: Auto);
+    optional(): ArrayFieldBuilder<ItemKind, false, Auto>;
+    default(value: unknown[]): ArrayFieldBuilder<ItemKind, false, Auto>;
+    auto(): ArrayFieldBuilder<ItemKind, false, true>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Type builder namespace. The developer's primary interface for defining field types.
+ *
+ * @example
+ * ```typescript
+ * import { t } from '@korajs/core'
+ *
+ * const fields = {
+ *   title: t.string(),
+ *   count: t.number(),
+ *   active: t.boolean().default(true),
+ *   notes: t.richtext(),
+ *   tags: t.array(t.string()).default([]),
+ *   priority: t.enum(['low', 'medium', 'high']).default('medium'),
+ *   createdAt: t.timestamp().auto(),
+ * }
+ * ```
+ */
+declare const t: {
+    string(): FieldBuilder<"string", true, false>;
+    number(): FieldBuilder<"number", true, false>;
+    boolean(): FieldBuilder<"boolean", true, false>;
+    timestamp(): FieldBuilder<"timestamp", true, false>;
+    richtext(): FieldBuilder<"richtext", true, false>;
+    enum<const V extends readonly string[]>(values: V): EnumFieldBuilder<V, true, false>;
+    array<K extends FieldKind>(itemBuilder: FieldBuilder<K>): ArrayFieldBuilder<K, true, false>;
+};
+
+/**
+ * Input shape for defineSchema() — what the developer writes.
+ */
+interface SchemaInput {
+    version: number;
+    collections: Record<string, CollectionInput>;
+    relations?: Record<string, RelationInput>;
+}
+interface CollectionInput {
+    fields: Record<string, FieldBuilder<any, any, any>>;
+    indexes?: string[];
+    constraints?: ConstraintInput[];
+    resolve?: Record<string, CustomResolver>;
+}
+interface ConstraintInput {
+    type: 'unique' | 'capacity' | 'referential';
+    fields: string[];
+    where?: Record<string, unknown>;
+    onConflict: 'first-write-wins' | 'last-write-wins' | 'priority-field' | 'server-decides' | 'custom';
+    priorityField?: string;
+    resolve?: (local: unknown, remote: unknown, base: unknown) => unknown;
+}
+interface RelationInput {
+    from: string;
+    to: string;
+    type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+    field: string;
+    onDelete: 'cascade' | 'set-null' | 'restrict' | 'no-action';
+}
+/**
+ * Validates and builds a SchemaDefinition from developer input.
+ * This is the primary developer-facing function for defining a schema.
+ *
+ * @param input - The schema definition using type builders
+ * @returns A validated SchemaDefinition ready for use by the framework
+ * @throws {SchemaValidationError} If the schema is invalid
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema, t } from '@korajs/core'
+ *
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     todos: {
+ *       fields: {
+ *         title: t.string(),
+ *         completed: t.boolean().default(false),
+ *       }
+ *     }
+ *   }
+ * })
+ * ```
+ */
+/**
+ * Schema definition with a phantom type brand preserving the original input shape.
+ * The `__input` property exists only at the type level for inference — no runtime cost.
+ */
+type TypedSchemaDefinition<T extends SchemaInput = SchemaInput> = SchemaDefinition & {
+    readonly __input: T;
+};
+declare function defineSchema<const T extends SchemaInput>(input: T): TypedSchemaDefinition<T>;
+
+/**
+ * Generate CREATE TABLE and CREATE INDEX SQL for a single collection.
+ *
+ * @param collectionName - The collection name
+ * @param collection - The collection definition
+ * @param relations - Optional relations for FK references
+ * @returns An array of SQL statements (CREATE TABLE + CREATE INDEX)
+ */
+declare function generateSQL(collectionName: string, collection: CollectionDefinition, relations?: Record<string, RelationDefinition>): string[];
+/**
+ * Generate the full DDL for all collections plus metadata tables.
+ *
+ * @param schema - The complete schema definition
+ * @returns An array of all SQL statements needed to initialize the database
+ */
+declare function generateFullDDL(schema: SchemaDefinition): string[];
+
+/**
+ * Validates a record's data against a collection's field definitions.
+ * Applies defaults, rejects auto fields, and type-checks each value.
+ *
+ * @param collection - The collection name (for error messages)
+ * @param collectionDef - The collection definition from the schema
+ * @param data - The record data to validate
+ * @param operationType - The operation type ('insert', 'update', 'delete')
+ * @returns The validated and normalized data (with defaults applied)
+ * @throws {SchemaValidationError} If validation fails
+ */
+declare function validateRecord(collection: string, collectionDef: CollectionDefinition, data: Record<string, unknown>, operationType: OperationType): Record<string, unknown>;
+
+/**
+ * Type-level inference utilities for Kora schemas.
+ *
+ * These mapped types convert FieldBuilder type parameters into concrete
+ * TypeScript types, enabling full autocomplete and type checking from
+ * defineSchema() through createApp() to collection methods.
+ *
+ * Zero runtime cost — these are purely compile-time constructs.
+ */
+
+/**
+ * Maps a FieldKind string literal to its corresponding TypeScript type.
+ */
+interface FieldKindToType {
+    string: string;
+    number: number;
+    boolean: boolean;
+    timestamp: number;
+    richtext: Uint8Array;
+    enum: string;
+    array: unknown[];
+}
+/**
+ * Infers the TypeScript type for a single FieldBuilder.
+ * Handles base fields, enums (with literal union), and arrays (with typed items).
+ */
+type InferFieldType<F> = F extends EnumFieldBuilder<infer V, infer _Req, infer _Auto> ? V[number] : F extends ArrayFieldBuilder<infer K, infer _Req, infer _Auto> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, infer _Req, infer _Auto> ? FieldKindToType[K] : unknown;
+/**
+ * Infers the full record type returned from queries.
+ * Includes `id`, `createdAt`, `updatedAt` metadata fields.
+ * Optional/defaulted fields include `| null` in their type.
+ */
+type InferRecord<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    readonly id: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+} & {
+    readonly [K in keyof Fields]: Fields[K] extends FieldBuilder<any, true, any> ? InferFieldType<Fields[K]> : InferFieldType<Fields[K]> | null;
+};
+/**
+ * Helper: extract keys where the field is required and not auto.
+ */
+type RequiredInsertKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? K : never;
+}[keyof Fields];
+/**
+ * Helper: extract keys where the field is optional (not required) and not auto.
+ */
+type OptionalInsertKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? never : K;
+}[keyof Fields];
+/**
+ * Infers the insert input type.
+ * - Required non-auto fields are required keys
+ * - Optional/defaulted non-auto fields are optional keys
+ * - Auto fields are excluded entirely
+ */
+type InferInsertInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    [K in RequiredInsertKeys<Fields> & string]: InferFieldType<Fields[K]>;
+} & {
+    [K in OptionalInsertKeys<Fields> & string]?: InferFieldType<Fields[K]>;
+};
+/**
+ * Helper: extract keys where the field is not auto.
+ */
+type NonAutoKeys<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    [K in keyof Fields]: Fields[K] extends FieldBuilder<any, any, true> ? never : K;
+}[keyof Fields];
+/**
+ * Infers the update input type.
+ * All non-auto fields are optional (partial update semantics).
+ */
+type InferUpdateInput<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
+    [K in NonAutoKeys<Fields> & string]?: InferFieldType<Fields[K]>;
+};
+
+/**
+ * Create an empty version vector.
+ */
+declare function createVersionVector(): VersionVector;
+/**
+ * Merge two version vectors by taking the max sequence number for each node.
+ * This is commutative, associative, and idempotent.
+ */
+declare function mergeVectors(a: VersionVector, b: VersionVector): VersionVector;
+/**
+ * Advance a version vector for a specific node to a new sequence number.
+ * Only advances forward — if the current value is higher, no change is made.
+ */
+declare function advanceVector(vector: VersionVector, nodeId: string, seq: number): VersionVector;
+/**
+ * Returns true if vector `a` dominates vector `b` — meaning `a` has seen
+ * everything `b` has seen. Formally: for every nodeId in b, a[nodeId] >= b[nodeId].
+ */
+declare function dominates(a: VersionVector, b: VersionVector): boolean;
+/**
+ * Returns true if two version vectors are exactly equal.
+ */
+declare function vectorsEqual(a: VersionVector, b: VersionVector): boolean;
+/**
+ * Operation log interface for computing deltas.
+ */
+interface OperationLog {
+    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[];
+}
+/**
+ * Compute the operations that `local` has but `remote` does not.
+ * Returns operations in causal (topological) order.
+ *
+ * @param localVector - The local version vector
+ * @param remoteVector - The remote version vector
+ * @param operationLog - The operation log to fetch operations from
+ * @returns Operations sorted in causal order
+ */
+declare function computeDelta(localVector: VersionVector, remoteVector: VersionVector, operationLog: OperationLog): Operation[];
+/**
+ * Serialize a version vector to a JSON-compatible string.
+ */
+declare function serializeVector(vector: VersionVector): string;
+/**
+ * Deserialize a version vector from its serialized string form.
+ */
+declare function deserializeVector(s: string): VersionVector;
+
+export { ArrayFieldBuilder, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldDescriptor, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, KoraError, MergeConflictError, Operation, OperationError, type OperationLog, OperationType, RandomSource, RelationDefinition, type RelationInput, SchemaDefinition, type SchemaInput, SchemaValidationError, StorageError, SyncError, type TypedSchemaDefinition, VersionVector, advanceVector, computeDelta, createVersionVector, defineSchema, deserializeVector, dominates, extractTimestamp, generateFullDDL, generateSQL, generateUUIDv7, isValidUUIDv7, mergeVectors, serializeVector, t, validateRecord, vectorsEqual };