@korajs/core 1.0.0-beta.2 → 1.0.0-beta.5

package/dist/index.d.cts

@@ -359,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -437,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -1077,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };

package/dist/index.d.ts

@@ -359,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -437,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -1077,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };

package/dist/index.js

@@ -365,32 +365,36 @@ var KORA_ATOMIC_OP = /* @__PURE__ */ Symbol.for("kora.atomic_op");
 function isAtomicOp(value) {
   return typeof value === "object" && value !== null && KORA_ATOMIC_OP in value && value[KORA_ATOMIC_OP] === true;
 }
-function resolveAtomicOp(currentValue, sentinel) {
-  switch (sentinel.type) {
+function applyAtomicOp(currentValue, atomicOp) {
+  switch (atomicOp.type) {
     case "increment": {
       const current = typeof currentValue === "number" ? currentValue : 0;
-      const operand = sentinel.value;
+      const operand = atomicOp.value;
       return current + operand;
     }
     case "max": {
       const current = typeof currentValue === "number" ? currentValue : Number.NEGATIVE_INFINITY;
-      return Math.max(current, sentinel.value);
+      return Math.max(current, atomicOp.value);
     }
     case "min": {
       const current = typeof currentValue === "number" ? currentValue : Number.POSITIVE_INFINITY;
-      return Math.min(current, sentinel.value);
+      return Math.min(current, atomicOp.value);
     }
     case "append": {
       const current = Array.isArray(currentValue) ? [...currentValue] : [];
-      current.push(sentinel.value);
+      current.push(atomicOp.value);
       return current;
     }
     case "remove": {
       if (!Array.isArray(currentValue)) return [];
-      return currentValue.filter((item) => item !== sentinel.value);
+      const target = JSON.stringify(atomicOp.value);
+      return currentValue.filter((item) => JSON.stringify(item) !== target);
     }
   }
 }
+function resolveAtomicOp(currentValue, sentinel) {
+  return applyAtomicOp(currentValue, { type: sentinel.type, value: sentinel.value });
+}
 function createSentinel(type, value) {
   return Object.freeze({
     [KORA_ATOMIC_OP]: true,
@@ -458,6 +462,46 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/operations/replay-record.ts
+function replayOperationsForRecord(ops) {
+  let record = null;
+  let deleted = false;
+  const lastWriterKind = {};
+  for (const op2 of ops) {
+    switch (op2.type) {
+      case "insert":
+        if (op2.data) {
+          record = { ...op2.data };
+          deleted = false;
+          for (const field of Object.keys(op2.data)) {
+            lastWriterKind[field] = "lww";
+          }
+        }
+        break;
+      case "update":
+        if (op2.data) {
+          const next = { ...record ?? {} };
+          for (const [field, value] of Object.entries(op2.data)) {
+            const atomicOp = op2.atomicOps?.[field];
+            if (atomicOp && lastWriterKind[field] === `atomic:${atomicOp.type}`) {
+              next[field] = applyAtomicOp(next[field], atomicOp);
+            } else {
+              next[field] = value;
+            }
+            lastWriterKind[field] = atomicOp ? `atomic:${atomicOp.type}` : "lww";
+          }
+          record = next;
+          deleted = false;
+        }
+        break;
+      case "delete":
+        deleted = true;
+        break;
+    }
+  }
+  return deleted ? null : record;
+}
+
 // src/operations/op-data-binary.ts
 function isKoraBytesValue(value) {
   if (typeof value !== "object" || value === null) {
@@ -2561,6 +2605,7 @@ export {
   StorageError,
   SyncError,
   advanceVector,
+  applyAtomicOp,
   applyOperationTransforms,
   base64ToBytes,
   buildScopeMap,
@@ -2610,6 +2655,7 @@ export {
   migrationStepsToSQL,
   op,
   quoteIdent,
+  replayOperationsForRecord,
   resolveAtomicOp,
   revealSecret,
   rollbackStepsToSQL,