@korajs/core 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
-import { R as RandomSource, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, C as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, d as ArrayFieldBuilder, e as Operation, V as VersionVector, f as MigrationStep, g as StateMachineConstraint, T as TransitionMap, h as TransitionValidationResult } from './events-BMulupSB.cjs';
-export { i as CONNECTION_QUALITIES, j as ConnectionQuality, k as Constraint, l as FieldDescriptor, m as FieldKind, n as FieldMergeStrategy, H as HLCTimestamp, o as HybridLogicalClock, K as KoraEvent, p as KoraEventByType, q as KoraEventEmitter, r as KoraEventListener, s as KoraEventType, t as MERGE_STRATEGIES, u as MergeStrategy, v as MergeTrace, w as MigrationBuilder, x as OnDeleteAction, y as OperationInput, z as RelationType, B as RollbackBuilder, D as SequenceConfig, G as StateMachineDefinition, I as SyncDiagnosticsSnapshot, J as TimeSource, L as createOperation, N as isValidOperation, P as migrate, Q as t, U as verifyOperationIntegrity } from './events-BMulupSB.cjs';
+import { R as RandomSource, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, C as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-D-FWfFg8.cjs';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, B as SequenceConfig, D as StateMachineDefinition, G as SyncDiagnosticsSnapshot, I as SyncRuleDefinition, J as TimeSource, L as migrate, N as t } from './events-D-FWfFg8.cjs';
+export { H as HybridLogicalClock, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-3-ZJJf3w.cjs';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-B1CcncZN.cjs';
 
 /**
  * Base error class for all Kora errors.
@@ -9,6 +11,10 @@ declare class KoraError extends Error {
     readonly code: string;
     readonly context?: Record<string, unknown> | undefined;
     constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+    /**
+     * Actionable hint for resolving this error (from registry or error context).
+     */
+    get fix(): string | undefined;
 }
 /**
  * Thrown when schema validation fails during defineSchema() or at app initialization.
@@ -55,6 +61,12 @@ declare class SyncError extends KoraError {
 declare class StorageError extends KoraError {
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown when collection/query APIs are used before {@link KoraApp.ready} resolves.
+ */
+declare class AppNotReadyError extends KoraError {
+    constructor(detail: string);
+}
 /**
  * Thrown when the HLC detects excessive clock drift.
  * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
@@ -65,6 +77,41 @@ declare class ClockDriftError extends KoraError {
     constructor(currentHlcTime: number, physicalTime: number);
 }
 
+/**
+ * Human-readable remediation hints keyed by {@link KoraError} `code`.
+ */
+declare const KORA_ERROR_FIX_SUGGESTIONS: Record<string, string>;
+/**
+ * Returns a suggested fix for a Kora error code, if one is known.
+ */
+declare function getKoraErrorFix(code: string): string | undefined;
+
+/**
+ * Tracks the latest operation per collection and within an open transaction
+ * to populate {@link Operation.causalDeps} for local mutations.
+ */
+declare class CausalTracker {
+    private readonly lastOpIdByCollection;
+    private lastTransactionOpId;
+    /**
+     * Start a new transaction boundary. Clears in-transaction op ids.
+     */
+    beginTransaction(): void;
+    /**
+     * Clear the transaction boundary without recording ops (after rollback).
+     */
+    clearTransaction(): void;
+    /**
+     * Compute causal dependencies for the next operation in a collection.
+     * Uses direct parents only: collection head and the previous op in the open transaction.
+     */
+    nextCausalDeps(collection: string, inTransaction: boolean): string[];
+    /**
+     * Record an operation after it has been created and assigned an id.
+     */
+    afterOperation(collection: string, operationId: string, inTransaction: boolean): void;
+}
+
 /**
  * Generates a UUID v7 per RFC 9562.
  * UUID v7 encodes a Unix timestamp in milliseconds in the most significant 48 bits,
@@ -97,6 +144,38 @@ declare function extractTimestamp(uuid: string): number;
  */
 declare function isValidUUIDv7(uuid: string): boolean;
 
+/**
+ * Outcome of applying a single operation to materialized storage (local or remote).
+ */
+declare const APPLY_RESULTS: readonly ["applied", "duplicate", "skipped", "rejected", "deferred"];
+type ApplyResult = (typeof APPLY_RESULTS)[number];
+/**
+ * Structured failure metadata when apply returns `skipped`, `rejected`, or `deferred`.
+ */
+interface ApplyFailureReason {
+    code: string;
+    message: string;
+    retriable: boolean;
+}
+/** Well-known apply failure codes for DevTools and `sync:apply-failed` events. */
+declare const APPLY_FAILURE_CODES: {
+    readonly APPLY_FAILED: "APPLY_FAILED";
+    readonly APPLY_SKIPPED: "APPLY_SKIPPED";
+    readonly APPLY_REJECTED: "APPLY_REJECTED";
+    readonly APPLY_DEFERRED: "APPLY_DEFERRED";
+    readonly CLOCK_DRIFT: "CLOCK_DRIFT";
+    readonly REFERENTIAL_INTEGRITY: "REFERENTIAL_INTEGRITY";
+    readonly SCHEMA_MISMATCH: "SCHEMA_MISMATCH";
+};
+/**
+ * Returns true when the apply outcome should surface as a failure to the developer.
+ */
+declare function isApplyFailure(result: ApplyResult): boolean;
+/**
+ * Default failure metadata when the store does not attach a specific reason.
+ */
+declare function defaultApplyFailureReason(result: Exclude<ApplyResult, 'applied' | 'duplicate'>, overrides?: Partial<ApplyFailureReason>): ApplyFailureReason;
+
 /**
  * Atomic field operations for intent-preserving updates.
  *
@@ -219,6 +298,29 @@ interface SchemaInput {
     relations?: Record<string, RelationInput>;
     /** Schema migrations keyed by target version number. */
     migrations?: Record<number, MigrationDefinition>;
+    /**
+     * Declarative partial-sync rules.
+     *
+     * @example
+     * ```typescript
+     * sync: {
+     *   todos: { where: { userId: true, orgId: true } },
+     *   projects: { where: { orgId: true } },
+     * }
+     * ```
+     */
+    sync?: Record<string, SyncRuleInput>;
+}
+/**
+ * Developer input for a collection sync rule.
+ */
+interface SyncRuleInput {
+    /**
+     * Field filters bound to scope values.
+     * Use `true` to bind a field to a scope value with the same name.
+     * Use a string to bind to a different scope value key.
+     */
+    where: Record<string, boolean | string>;
 }
 interface StateMachineInput {
     /** The enum field this state machine controls */
@@ -335,15 +437,23 @@ interface FieldKindToType {
     number: number;
     boolean: boolean;
     timestamp: number;
-    richtext: Uint8Array;
+    richtext: string;
     enum: string;
     array: unknown[];
 }
 /**
- * Infers the TypeScript type for a single FieldBuilder.
- * Handles base fields, enums (with literal union), and arrays (with typed items).
+ * Infers the TypeScript type for a single field descriptor or builder.
+ * Supports both FieldBuilder (class instances) and FieldDescriptor (compiled objects).
  */
-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;
+type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
+    kind: 'enum';
+    enumValues: infer V;
+} ? V extends readonly (infer S)[] ? S : string : F extends {
+    kind: 'array';
+    itemKind: infer K extends FieldKind;
+} ? FieldKindToType[K][] : F extends {
+    kind: infer K extends FieldKind;
+} ? FieldKindToType[K] : unknown;
 /**
  * Infers the full record type returned from queries.
  * Includes `id`, `createdAt`, `updatedAt` metadata fields.
@@ -357,40 +467,22 @@ type InferRecord<Fields extends Record<string, FieldBuilder<any, any, any>>> = {
     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.
+ * Infers the insert input type using inline key remapping.
  * - 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 keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? K : never]: InferFieldType<Fields[K]>;
 } & {
-    [K in OptionalInsertKeys<Fields> & string]?: InferFieldType<Fields[K]>;
+    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : Fields[K] extends FieldBuilder<any, true, false> ? never : K]?: 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.
+ * Infers the update input type using inline key remapping.
  * 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]>;
+    [K in keyof Fields as Fields[K] extends FieldBuilder<any, any, true> ? never : K]?: InferFieldType<Fields[K]>;
 };
 
 /**
@@ -418,9 +510,10 @@ declare function dominates(a: VersionVector, b: VersionVector): boolean;
 declare function vectorsEqual(a: VersionVector, b: VersionVector): boolean;
 /**
  * Operation log interface for computing deltas.
+ * getRange may be async (for DB-backed implementations) or sync (for in-memory).
  */
 interface OperationLog {
-    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[];
+    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[] | Promise<Operation[]>;
 }
 /**
  * Compute the operations that `local` has but `remote` does not.
@@ -431,7 +524,7 @@ interface OperationLog {
  * @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[];
+declare function computeDelta(localVector: VersionVector, remoteVector: VersionVector, operationLog: OperationLog): Promise<Operation[]>;
 /**
  * Serialize a version vector to a JSON-compatible string.
  */
@@ -442,31 +535,44 @@ declare function serializeVector(vector: VersionVector): string;
 declare function deserializeVector(s: string): VersionVector;
 
 /**
- * Per-collection scope map: `{ collectionName: { field: value, ... } }`
+ * Returns true when the schema declares partial sync rules at the root level.
+ */
+declare function hasSchemaSyncRules(schema: SchemaDefinition): boolean;
+/**
+ * Resolve field → scope-value-key bindings for a collection.
  *
- * Used to filter which operations a client should receive during sync.
+ * Sync rules take precedence over legacy `collection.scope` arrays.
+ * Returns `null` when the collection has no sync filtering configured.
  */
-type ScopeMap = Record<string, Record<string, unknown>>;
+declare function getCollectionScopeBindings(schema: SchemaDefinition, collectionName: string): Record<string, string> | null;
 /**
- * Build a per-collection scope map from the schema's scope declarations
- * and the client's flat scope values.
+ * Returns whether a collection participates in sync filtering for this schema.
+ */
+declare function isCollectionSyncScoped(schema: SchemaDefinition, collectionName: string): boolean;
+/**
+ * Collect unique scope value keys referenced by sync rules and legacy scope fields.
+ */
+declare function collectSchemaScopeValueKeys(schema: SchemaDefinition): string[];
+
+/**
+ * Collect every unique scope field name declared across all collections.
  *
- * For each collection:
- * - If it declares scope fields, build a filter from the matching flat values.
- * - If it declares no scope fields, include it with an empty filter (no restriction).
+ * @deprecated Use {@link collectSchemaScopeValueKeys} instead.
+ */
+declare function collectSchemaScopeFields(schema: SchemaDefinition): string[];
+/**
+ * Extract flat scope values from JWT (or auth) claims using schema scope field names.
  *
- * @param schema - The schema definition with scope declarations
- * @param scopeValues - Flat key-value scope values from the client
- * @returns A per-collection scope map
+ * Resolution order for each scope field:
+ * 1. Top-level claim with the same name
+ * 2. Nested `claims.scope[field]` object
+ * 3. `userId` falls back to the standard JWT `sub` claim
  *
- * @example
- * ```typescript
- * // Schema declares: sales.scope = ['orgId', 'storeId']
- * // Client provides: { orgId: 'org-123', storeId: 'store-456' }
- * // Result: { sales: { orgId: 'org-123', storeId: 'store-456' }, products: {} }
- * ```
+ * @param schema - Schema with per-collection scope declarations
+ * @param claims - Decoded JWT claims (unverified; client-side scope hints only)
+ * @returns Flat key-value map suitable for {@link buildScopeMap}
  */
-declare function buildScopeMap(schema: SchemaDefinition, scopeValues: Record<string, unknown>): ScopeMap;
+declare function extractScopeValuesFromClaims(schema: SchemaDefinition, claims: Record<string, unknown>): Record<string, unknown>;
 
 /**
  * Offline-safe sequence formatting.
@@ -493,6 +599,28 @@ declare function formatSequenceValue(template: string, counter: number, nodeId:
  */
 declare function defaultSequenceFormat(name: string): string;
 
+/**
+ * Transforms operations created under an older schema version so they are valid
+ * after a schema upgrade. Used during sync when client and server schema versions differ
+ * but remain within the server's supported range.
+ */
+interface OperationTransform {
+    /** Schema version the operation was authored against */
+    readonly fromVersion: number;
+    /** Target schema version after transformation */
+    readonly toVersion: number;
+    /**
+     * Transform a single operation. Return `null` to drop operations that cannot be migrated.
+     */
+    transform(operation: Operation): Operation | null;
+}
+
+/**
+ * Apply registered transforms until the operation matches `targetSchemaVersion`.
+ * Returns null when a transform drops the operation or no path exists.
+ */
+declare function applyOperationTransforms(operation: Operation, targetSchemaVersion: number, transforms: readonly OperationTransform[]): Operation | null;
+
 /**
  * Convert migration steps to SQL statements.
  *
@@ -714,4 +842,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type ScopeMap, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, buildScopeMap, buildStateMachineConstraints, canAutoRollback, computeDelta, createReversibleMigration, createVersionVector, defaultSequenceFormat, defineSchema, deserializeVector, dominates, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getTransitionMap, isAtomicOp, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, KORA_ERROR_FIX_SUGGESTIONS, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, buildStateMachineConstraints, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };