@korajs/core 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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-7Fhdjxd2.cjs';
-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-7Fhdjxd2.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 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';
 
 /**
  * Base error class for all Kora errors.
@@ -98,88 +98,117 @@ declare function extractTimestamp(uuid: string): number;
 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.
+ * Atomic field operations for intent-preserving updates.
  *
- * 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
+ * Instead of read-modify-write patterns, developers express intent:
  * ```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
+ * await app.stock.update(id, { quantity: op.increment(-5) })
  * ```
+ *
+ * The operation intent is preserved in the Operation for merge:
+ * concurrent increments compose (sum of deltas) instead of LWW.
  */
-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.
+ * Sentinel marker for detecting atomic op objects in update data.
+ * Uses Symbol.for() so the sentinel survives module boundary crossings.
  */
-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;
-}
+declare const KORA_ATOMIC_OP: unique symbol;
+/** String key used for the sentinel symbol — exported for internal use */
+declare const KORA_ATOMIC_OP_KEY: typeof KORA_ATOMIC_OP;
 /**
- * Field builder for array fields with a typed item kind.
- * Preserves the item kind type parameter for inference.
+ * Sentinel object returned by op.* helpers.
+ * Detected by Collection.update() and resolved to concrete values.
  */
-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;
+interface AtomicOpSentinel {
+    readonly [KORA_ATOMIC_OP_KEY]: true;
+    readonly type: AtomicOpType;
+    readonly value: unknown;
 }
 /**
- * Type builder namespace. The developer's primary interface for defining field types.
+ * Type guard: checks whether a value is an atomic op sentinel.
+ *
+ * @param value - Any value to check
+ * @returns true if the value is an AtomicOpSentinel
+ */
+declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Resolve an atomic op sentinel against a current value to produce a concrete result.
+ *
+ * @param currentValue - The current value of the field in the database
+ * @param sentinel - The atomic op sentinel from the developer's update call
+ * @returns The resolved concrete value
+ */
+declare function resolveAtomicOp(currentValue: unknown, sentinel: AtomicOpSentinel): unknown;
+/**
+ * Atomic operation helpers. Use these in collection.update() calls
+ * to express intent-preserving mutations.
  *
  * @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(),
- * }
+ * import { op } from 'korajs'
+ *
+ * // Increment a counter (works correctly with concurrent updates)
+ * await app.stock.update(id, { quantity: op.increment(-5) })
+ *
+ * // Keep the maximum value
+ * await app.scores.update(id, { highScore: op.max(newScore) })
+ *
+ * // Append to an array
+ * await app.todos.update(id, { tags: op.append('urgent') })
  * ```
  */
-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>;
+declare const op: {
+    /**
+     * Increment a number field by the given amount.
+     * Concurrent increments compose: the sum of all deltas is applied to the base.
+     *
+     * @param n - The amount to increment (use negative values to decrement)
+     */
+    increment(n: number): AtomicOpSentinel;
+    /**
+     * Decrement a number field by the given amount.
+     * Syntactic sugar for `op.increment(-n)`.
+     *
+     * @param n - The amount to decrement
+     */
+    decrement(n: number): AtomicOpSentinel;
+    /**
+     * Set the field to the maximum of the current value and the given value.
+     * Concurrent max operations take the maximum of all values.
+     *
+     * @param n - The value to compare against the current value
+     */
+    max(n: number): AtomicOpSentinel;
+    /**
+     * Set the field to the minimum of the current value and the given value.
+     * Concurrent min operations take the minimum of all values.
+     *
+     * @param n - The value to compare against the current value
+     */
+    min(n: number): AtomicOpSentinel;
+    /**
+     * Append an item to an array field.
+     * Concurrent appends include all appended items.
+     *
+     * @param item - The item to append to the array
+     */
+    append(item: unknown): AtomicOpSentinel;
+    /**
+     * Remove an item from an array field (by value equality).
+     * Concurrent removes of the same item are idempotent.
+     *
+     * @param item - The item to remove from the array
+     */
+    remove(item: unknown): AtomicOpSentinel;
 };
+/**
+ * Extract the serializable AtomicOp from a sentinel (strips the Symbol marker).
+ *
+ * @param sentinel - The atomic op sentinel
+ * @returns A plain object suitable for JSON serialization
+ */
+declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
 /**
  * Input shape for defineSchema() — what the developer writes.
@@ -188,12 +217,26 @@ interface SchemaInput {
     version: number;
     collections: Record<string, CollectionInput>;
     relations?: Record<string, RelationInput>;
+    /** Schema migrations keyed by target version number. */
+    migrations?: Record<number, MigrationDefinition>;
+}
+interface StateMachineInput {
+    /** The enum field this state machine controls */
+    field: string;
+    /** Map of state to allowed next states */
+    transitions: Record<string, string[]>;
+    /** What to do when an invalid transition is attempted */
+    onInvalidTransition: 'reject' | 'last-valid-state';
 }
 interface CollectionInput {
     fields: Record<string, FieldBuilder<any, any, any>>;
     indexes?: string[];
     constraints?: ConstraintInput[];
     resolve?: Record<string, CustomResolver>;
+    /** Scope fields for sync filtering. Only records matching the client's scope values are synced. */
+    scope?: string[];
+    /** State machine definition constraining transitions on an enum field */
+    stateMachine?: StateMachineInput;
 }
 interface ConstraintInput {
     type: 'unique' | 'capacity' | 'referential';
@@ -398,4 +441,277 @@ declare function serializeVector(vector: VersionVector): string;
  */
 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 };
+/**
+ * Per-collection scope map: `{ collectionName: { field: value, ... } }`
+ *
+ * Used to filter which operations a client should receive during sync.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+/**
+ * Build a per-collection scope map from the schema's scope declarations
+ * and the client's flat scope values.
+ *
+ * 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).
+ *
+ * @param schema - The schema definition with scope declarations
+ * @param scopeValues - Flat key-value scope values from the client
+ * @returns A per-collection scope map
+ *
+ * @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: {} }
+ * ```
+ */
+declare function buildScopeMap(schema: SchemaDefinition, scopeValues: Record<string, unknown>): ScopeMap;
+
+/**
+ * Offline-safe sequence formatting.
+ *
+ * Format tokens:
+ * - `{date}` → YYYYMMDD (current date)
+ * - `{node4}` → first 4 characters of nodeId
+ * - `{node8}` → first 8 characters of nodeId
+ * - `{seq}` → zero-padded counter (default 4 digits)
+ * - `{seq:N}` → zero-padded counter with N digits
+ *
+ * @example
+ * ```typescript
+ * formatSequenceValue('INV-{date}-{node4}-{seq}', 42, 'a1b2c3d4e5f6')
+ * // → "INV-20260508-a1b2-0042"
+ *
+ * formatSequenceValue('ORDER-{seq:6}', 7, 'node-id')
+ * // → "ORDER-000007"
+ * ```
+ */
+declare function formatSequenceValue(template: string, counter: number, nodeId: string, now?: Date): string;
+/**
+ * Default format when none is provided: `{name}-{seq:4}`.
+ */
+declare function defaultSequenceFormat(name: string): string;
+
+/**
+ * Convert migration steps to SQL statements.
+ *
+ * Structural steps (addField, removeField, renameField, addIndex, removeIndex)
+ * produce SQL. Backfill steps are skipped (handled at the application layer
+ * by reading rows and applying the transform function).
+ *
+ * @param steps - The migration steps from a MigrationBuilder
+ * @returns Array of SQL statements for structural changes
+ */
+declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
+/**
+ * Generate SQL statements to roll back a migration.
+ *
+ * Uses the migration's explicit rollback steps if available,
+ * otherwise auto-generates inverse steps from the forward steps.
+ *
+ * Backfill steps in the rollback are skipped (handled at the application layer).
+ *
+ * @param migration - The migration definition to generate rollback SQL for
+ * @returns Array of SQL statements that undo the migration's structural changes
+ *
+ * @example
+ * ```typescript
+ * const migration = migrate()
+ *   .addField('todos', 'priority', t.enum(['low', 'medium', 'high']).default('medium'))
+ *   .addIndex('todos', 'priority')
+ *
+ * const rollbackSQL = rollbackStepsToSQL(migration)
+ * // ['DROP INDEX IF EXISTS idx_todos_priority',
+ * //  'ALTER TABLE todos DROP COLUMN priority']
+ * ```
+ */
+declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
+
+/**
+ * A migration that includes both forward (up) and backward (down) steps.
+ * Rollback steps are applied in reverse order of the forward steps.
+ */
+interface ReversibleMigration {
+    readonly up: readonly MigrationStep[];
+    readonly down: readonly MigrationStep[];
+    readonly fromVersion: number;
+    readonly toVersion: number;
+}
+/**
+ * Error thrown when a migration step cannot be automatically rolled back
+ * and no explicit down step has been provided.
+ */
+declare class MigrationRollbackError extends KoraError {
+    constructor(step: MigrationStep);
+}
+/**
+ * Determines whether a migration step can be automatically rolled back
+ * without explicit developer-provided down steps.
+ *
+ * Auto-rollback is possible when the inverse operation is deterministic:
+ * - addField -> removeField (drop the added column)
+ * - addIndex -> removeIndex (drop the added index)
+ * - removeIndex -> addIndex (re-create the index)
+ * - renameField -> renameField (swap from/to names)
+ *
+ * Steps that CANNOT auto-rollback:
+ * - removeField: the field descriptor is lost (need it to re-create the column)
+ * - backfill: data transforms are not reversible
+ *
+ * @param step - The forward migration step to check
+ * @returns true if the step can be auto-rolled back
+ */
+declare function canAutoRollback(step: MigrationStep): boolean;
+/**
+ * Generates rollback steps for a list of forward migration steps.
+ * Steps are reversed in order (last forward step becomes first rollback step).
+ *
+ * For steps that cannot be auto-rolled back, throws a MigrationRollbackError.
+ * Use canAutoRollback() to check before calling, or provide explicit down steps
+ * via the MigrationBuilder .down() API.
+ *
+ * @param forwardSteps - The forward migration steps to generate rollbacks for
+ * @returns Array of rollback steps in reverse execution order
+ * @throws MigrationRollbackError if any step cannot be auto-rolled back
+ */
+declare function generateRollbackSteps(forwardSteps: readonly MigrationStep[]): MigrationStep[];
+/**
+ * Create a ReversibleMigration from forward steps, explicit down steps, and version info.
+ *
+ * If explicit down steps are provided, they are used as-is.
+ * If no explicit down steps are provided, auto-generation is attempted.
+ *
+ * @param upSteps - The forward migration steps
+ * @param downSteps - Optional explicit rollback steps (overrides auto-generation)
+ * @param fromVersion - The schema version before the migration
+ * @param toVersion - The schema version after the migration
+ * @returns A complete ReversibleMigration
+ * @throws MigrationRollbackError if auto-generation fails and no explicit down steps provided
+ */
+declare function createReversibleMigration(upSteps: readonly MigrationStep[], downSteps: readonly MigrationStep[] | null, fromVersion: number, toVersion: number): ReversibleMigration;
+
+/**
+ * Validates whether a transition from one state to another is allowed
+ * by the given state machine constraint.
+ *
+ * @param constraint - The state machine constraint defining allowed transitions
+ * @param fromValue - The current state value (before the transition)
+ * @param toValue - The target state value (after the transition)
+ * @returns A TransitionValidationResult describing whether the transition is valid
+ *
+ * @example
+ * ```typescript
+ * const constraint: StateMachineConstraint = {
+ *   field: 'status',
+ *   collection: 'orders',
+ *   transitions: {
+ *     draft: ['submitted', 'cancelled'],
+ *     submitted: ['approved'],
+ *     approved: [],
+ *   },
+ * }
+ *
+ * const result = validateTransition(constraint, 'draft', 'submitted')
+ * // { valid: true, from: 'draft', to: 'submitted', field: 'status',
+ * //   collection: 'orders', allowedTargets: ['submitted', 'cancelled'] }
+ * ```
+ */
+declare function validateTransition(constraint: StateMachineConstraint, fromValue: unknown, toValue: unknown): TransitionValidationResult;
+/**
+ * Extracts all state machine constraints from a schema definition.
+ * Scans every collection for enum fields that have transition rules declared
+ * via the `.transitions()` builder method.
+ *
+ * @param schema - The schema definition to extract constraints from
+ * @returns An array of StateMachineConstraint objects, one per enum field with transitions
+ *
+ * @example
+ * ```typescript
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     orders: {
+ *       fields: {
+ *         status: t.enum(['draft', 'submitted']).transitions({
+ *           draft: ['submitted'],
+ *           submitted: [],
+ *         }),
+ *       },
+ *     },
+ *   },
+ * })
+ *
+ * const constraints = buildStateMachineConstraints(schema)
+ * // [{ field: 'status', collection: 'orders', transitions: { draft: ['submitted'], submitted: [] } }]
+ * ```
+ */
+declare function buildStateMachineConstraints(schema: SchemaDefinition): StateMachineConstraint[];
+/**
+ * Finds the state machine constraint for a specific field in a specific collection,
+ * if one exists.
+ *
+ * @param schema - The schema definition to search
+ * @param collection - The collection name
+ * @param field - The field name
+ * @returns The TransitionMap if the field has transitions declared, or null otherwise
+ */
+declare function getTransitionMap(schema: SchemaDefinition, collection: string, field: string): TransitionMap | null;
+
+/**
+ * Output of the proto definition generator.
+ * Contains the .proto file text, a type mapping, and a JSON descriptor
+ * compatible with protobufjs's `Root.fromJSON()`.
+ */
+interface ProtoOutput {
+    /** The generated .proto file content as a string */
+    proto: string;
+    /** TypeScript type map: field name -> protobuf type */
+    typeMap: Map<string, string>;
+    /** JSON descriptor for dynamic protobufjs usage (no .proto file needed) */
+    jsonDescriptor: Record<string, unknown>;
+}
+/**
+ * Generates Protocol Buffer definitions from a Kora schema.
+ *
+ * Produces three outputs:
+ * 1. A `.proto` file string conforming to proto3 syntax
+ * 2. A type map linking Kora field paths to protobuf types
+ * 3. A JSON descriptor for runtime protobufjs usage via `Root.fromJSON()`
+ *
+ * The generated definitions include:
+ * - Per-collection record messages with proper type mappings
+ * - Nested enum types for enum fields
+ * - `KoraOperation` wrapper for the sync wire format
+ * - `OperationBatch` for batched sync transfers
+ * - `HandshakeMessage` / `HandshakeResponse` for sync session initiation
+ * - `Acknowledgment` for delivery confirmation
+ *
+ * @param schema - A validated SchemaDefinition from defineSchema()
+ * @returns ProtoOutput with proto text, type map, and JSON descriptor
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema, t, generateProtoDefinitions } from '@korajs/core'
+ *
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     todos: {
+ *       fields: {
+ *         title: t.string(),
+ *         completed: t.boolean().default(false),
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * const { proto, typeMap, jsonDescriptor } = generateProtoDefinitions(schema)
+ * // proto is a valid .proto file string
+ * // typeMap maps "todos.title" -> "string", "todos.completed" -> "bool"
+ * // jsonDescriptor can be loaded with protobuf.Root.fromJSON()
+ * ```
+ */
+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 };