@korajs/server 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/index.d.cts

@@ -5,6 +5,32 @@ import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandle
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 
+/**
+ * Predicate evaluation for conditional route mutations.
+ *
+ * A predicate is a small, total comparison language evaluated against the current
+ * materialized state of a single record at admission time. It is deliberately not
+ * a general query language: it exists so a server route can express an atomic
+ * admission guard (for example "accept this response only while the form is still
+ * below its cap") without pulling a query DSL into the write path.
+ */
+/**
+ * Comparison operators applied to one field. All operators present on a field
+ * must hold for the field to match. Numeric operators (`$lt`, `$lte`, `$gt`,
+ * `$gte`) require the record value to be a number; a non-numeric value fails.
+ */
+interface RoutePredicateOperators {
+    $eq?: unknown;
+    $ne?: unknown;
+    $lt?: number;
+    $lte?: number;
+    $gt?: number;
+    $gte?: number;
+    $in?: readonly unknown[];
+}
+/** A predicate: every listed field must satisfy all of its operators. */
+type RoutePredicate = Record<string, RoutePredicateOperators>;
+
 /**
  * Per-collection scope map from auth context.
  */
@@ -463,6 +489,61 @@ type RouteApplyResult = {
     message: string;
     retriable: boolean;
 };
+/**
+ * A conditional, multi-collection admission gate applied atomically per instance.
+ *
+ * The gate reads the current state of the target record (`collection` + `id`),
+ * checks the `if` predicate against it, and only then applies the `update` to the
+ * target plus every mutation in `also` as one set. If the predicate fails it
+ * applies nothing and returns the structured `reject`. `idempotencyKey` names a
+ * record whose prior existence proves the set already committed, so a retry
+ * returns the earlier outcome instead of applying the set (and its non-idempotent
+ * counter increments) again.
+ *
+ * Atomicity note: within one server instance the check and the writes do not
+ * interleave with other route mutations. Cross-instance, race-free admission and
+ * all-or-nothing across a mid-set crash require the store-level conditional
+ * transaction (a Postgres `WHERE ... < cap` commit), which is the next increment.
+ */
+interface RouteConditionalApply {
+    /** Collection of the record the predicate reads and the `update` targets. */
+    collection: string;
+    /** Id of the target record. */
+    id: string;
+    /** Admission predicate evaluated against the target's current state. */
+    if?: RoutePredicate;
+    /** Partial update applied to the target record when the predicate holds. */
+    update?: Record<string, unknown> | null;
+    /** Additional mutations committed atomically with the target update. */
+    also?: RouteMutation[];
+    /** Structured rejection returned when the predicate does not hold. */
+    reject?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Names a record whose existence means this set already committed. When it is
+     * present the set is skipped and the prior outcome returned. Use a stable,
+     * client-generated id (for example the accepted record's own id).
+     */
+    idempotencyKey?: {
+        collection: string;
+        id: string;
+    };
+}
+/** Result of {@link ProductionHttpRouteContext.applyConditional}. */
+type RouteConditionalResult = {
+    ok: true;
+    /** True when the set was already committed and this call was a no-op. */
+    idempotent: boolean;
+    operations: Operation[];
+    records: (MaterializedRecord | null)[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retriable: boolean;
+};
 /**
  * Scoped, validated data-plane access handed to custom HTTP route handlers.
  *
@@ -477,6 +558,12 @@ interface ProductionHttpRouteContext {
      * resulting operation(s) to connected clients.
      */
     apply(mutation: RouteMutation, options?: RouteScopeOptions): Promise<RouteApplyResult>;
+    /**
+     * Conditionally apply a multi-collection mutation set as one admission gate:
+     * read the target, check the predicate, and commit the update plus every `also`
+     * mutation only if it holds, with at-most-once semantics via `idempotencyKey`.
+     */
+    applyConditional(spec: RouteConditionalApply, options?: RouteScopeOptions): Promise<RouteConditionalResult>;
     /** Read materialized records from a collection, optionally scoped. */
     query(collection: string, options?: CollectionQueryOptions & RouteScopeOptions): Promise<MaterializedRecord[]>;
     /** Read a single materialized record by id, optionally scoped. */
@@ -1562,4 +1649,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteMutation, type RouteScopeOptions, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection };

package/dist/index.d.ts

@@ -5,6 +5,32 @@ import { S as ServerTransport, a as ServerMessageHandler, b as ServerCloseHandle
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 
+/**
+ * Predicate evaluation for conditional route mutations.
+ *
+ * A predicate is a small, total comparison language evaluated against the current
+ * materialized state of a single record at admission time. It is deliberately not
+ * a general query language: it exists so a server route can express an atomic
+ * admission guard (for example "accept this response only while the form is still
+ * below its cap") without pulling a query DSL into the write path.
+ */
+/**
+ * Comparison operators applied to one field. All operators present on a field
+ * must hold for the field to match. Numeric operators (`$lt`, `$lte`, `$gt`,
+ * `$gte`) require the record value to be a number; a non-numeric value fails.
+ */
+interface RoutePredicateOperators {
+    $eq?: unknown;
+    $ne?: unknown;
+    $lt?: number;
+    $lte?: number;
+    $gt?: number;
+    $gte?: number;
+    $in?: readonly unknown[];
+}
+/** A predicate: every listed field must satisfy all of its operators. */
+type RoutePredicate = Record<string, RoutePredicateOperators>;
+
 /**
  * Per-collection scope map from auth context.
  */
@@ -463,6 +489,61 @@ type RouteApplyResult = {
     message: string;
     retriable: boolean;
 };
+/**
+ * A conditional, multi-collection admission gate applied atomically per instance.
+ *
+ * The gate reads the current state of the target record (`collection` + `id`),
+ * checks the `if` predicate against it, and only then applies the `update` to the
+ * target plus every mutation in `also` as one set. If the predicate fails it
+ * applies nothing and returns the structured `reject`. `idempotencyKey` names a
+ * record whose prior existence proves the set already committed, so a retry
+ * returns the earlier outcome instead of applying the set (and its non-idempotent
+ * counter increments) again.
+ *
+ * Atomicity note: within one server instance the check and the writes do not
+ * interleave with other route mutations. Cross-instance, race-free admission and
+ * all-or-nothing across a mid-set crash require the store-level conditional
+ * transaction (a Postgres `WHERE ... < cap` commit), which is the next increment.
+ */
+interface RouteConditionalApply {
+    /** Collection of the record the predicate reads and the `update` targets. */
+    collection: string;
+    /** Id of the target record. */
+    id: string;
+    /** Admission predicate evaluated against the target's current state. */
+    if?: RoutePredicate;
+    /** Partial update applied to the target record when the predicate holds. */
+    update?: Record<string, unknown> | null;
+    /** Additional mutations committed atomically with the target update. */
+    also?: RouteMutation[];
+    /** Structured rejection returned when the predicate does not hold. */
+    reject?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Names a record whose existence means this set already committed. When it is
+     * present the set is skipped and the prior outcome returned. Use a stable,
+     * client-generated id (for example the accepted record's own id).
+     */
+    idempotencyKey?: {
+        collection: string;
+        id: string;
+    };
+}
+/** Result of {@link ProductionHttpRouteContext.applyConditional}. */
+type RouteConditionalResult = {
+    ok: true;
+    /** True when the set was already committed and this call was a no-op. */
+    idempotent: boolean;
+    operations: Operation[];
+    records: (MaterializedRecord | null)[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retriable: boolean;
+};
 /**
  * Scoped, validated data-plane access handed to custom HTTP route handlers.
  *
@@ -477,6 +558,12 @@ interface ProductionHttpRouteContext {
      * resulting operation(s) to connected clients.
      */
     apply(mutation: RouteMutation, options?: RouteScopeOptions): Promise<RouteApplyResult>;
+    /**
+     * Conditionally apply a multi-collection mutation set as one admission gate:
+     * read the target, check the predicate, and commit the update plus every `also`
+     * mutation only if it holds, with at-most-once semantics via `idempotencyKey`.
+     */
+    applyConditional(spec: RouteConditionalApply, options?: RouteScopeOptions): Promise<RouteConditionalResult>;
     /** Read materialized records from a collection, optionally scoped. */
     query(collection: string, options?: CollectionQueryOptions & RouteScopeOptions): Promise<MaterializedRecord[]>;
     /** Read a single materialized record by id, optionally scoped. */
@@ -1562,4 +1649,4 @@ declare class AwarenessRelay {
  */
 declare function createKoraServer(config: KoraSyncServerConfig): KoraSyncServer;
 
-export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteMutation, type RouteScopeOptions, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection };
+export { type AuthContext, type AuthProvider, AwarenessRelay, type AwarenessRelayCallback, type ClientMetrics, ClientSession, type ClientSessionOptions, type CollectionQueryOptions, type HttpPollResponse, HttpServerTransport, type HttpSyncRequest, type HttpSyncResponse, KoraAuthProvider, type KoraAuthProviderOptions, KoraSyncServer, type KoraSyncServerConfig, type LogEntry, type LogLevel, type Logger, type MaterializedRecord, MemoryServerStore, MixedAuthProvider, type MixedAuthProviderOptions, NoAuthProvider, type OperationDecision, type OperationRejection, type OperationValidationContext, type OperationValidator, PostgresServerStore, type ProductionHttpRoute, type ProductionHttpRouteContext, type ProductionHttpRouteRequest, type ProductionHttpRouteResponse, type ProductionServer, type ProductionServerConfig, RETRIABLE_REJECTION_CODES, type RelayCallback, type RouteApplyResult, type RouteConditionalApply, type RouteConditionalResult, type RouteMutation, type RoutePredicate, type RoutePredicateOperators, type RouteScopeOptions, ServerCloseHandler, ServerErrorHandler, ServerMessageHandler, ServerMetricsCollector, type ServerMetricsSnapshot, type ServerStatus, type ServerStore, ServerTransport, type SessionState, SqliteServerStore, TokenAuthProvider, type TokenAuthProviderOptions, type WsServerConstructor, type WsServerLike, WsServerTransport, type WsServerTransportOptions, type WsWebSocket, createDefaultLogger, createJsonLogger, createKoraServer, createPostgresServerStore, createPrettyLogger, createProductionServer, createSilentLogger, createSqliteServerStore, isRetriableRejection };

package/dist/index.js

@@ -3068,7 +3068,64 @@ var YjsDocRelay = class {
 };
 
 // src/server/route-context.ts
-import { HybridLogicalClock as HybridLogicalClock2, createOperation as createOperation2, generateUUIDv7 as generateUUIDv76 } from "@korajs/core";
+import {
+  HybridLogicalClock as HybridLogicalClock2,
+  createOperation as createOperation2,
+  generateUUIDv7 as generateUUIDv76,
+  isAtomicOp,
+  resolveAtomicOp,
+  toAtomicOp
+} from "@korajs/core";
+
+// src/apply/route-predicate.ts
+function evaluateField(actual, operators) {
+  if ("$eq" in operators && !Object.is(actual, operators.$eq)) {
+    return false;
+  }
+  if ("$ne" in operators && Object.is(actual, operators.$ne)) {
+    return false;
+  }
+  if (operators.$in !== void 0 && !operators.$in.some((candidate) => Object.is(actual, candidate))) {
+    return false;
+  }
+  const numericChecks = [
+    ["$lt", (a, b) => a < b],
+    ["$lte", (a, b) => a <= b],
+    ["$gt", (a, b) => a > b],
+    ["$gte", (a, b) => a >= b]
+  ];
+  for (const [operator, compare] of numericChecks) {
+    const bound = operators[operator];
+    if (bound === void 0) {
+      continue;
+    }
+    if (typeof actual !== "number" || typeof bound !== "number") {
+      return false;
+    }
+    if (!compare(actual, bound)) {
+      return false;
+    }
+  }
+  return true;
+}
+function evaluateRoutePredicate(record, predicate) {
+  const fields = Object.keys(predicate);
+  if (fields.length === 0) {
+    return true;
+  }
+  if (record === null) {
+    return false;
+  }
+  for (const field of fields) {
+    const operators = predicate[field];
+    if (operators && !evaluateField(record[field], operators)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/server/route-context.ts
 function recordMatchesScope(collection, record, scope) {
   const collectionScope = scope[collection];
   if (!collectionScope) {
@@ -3119,7 +3176,18 @@ async function buildRouteOperation(store, mutation) {
   }
   const current = await store.findRecord(mutation.collection, mutation.recordId);
   if (mutation.type === "update") {
-    const data = mutation.data ?? {};
+    const rawData = mutation.data ?? {};
+    const data = {};
+    const atomicOps = {};
+    for (const key of Object.keys(rawData)) {
+      const value = rawData[key];
+      if (isAtomicOp(value)) {
+        data[key] = resolveAtomicOp(current ? current[key] : void 0, value);
+        atomicOps[key] = toAtomicOp(value);
+      } else {
+        data[key] = value;
+      }
+    }
     return createOperation2(
       {
         nodeId,
@@ -3127,10 +3195,11 @@ async function buildRouteOperation(store, mutation) {
         collection: mutation.collection,
         recordId: mutation.recordId,
         data,
-        previousData: current ? pickFields(current, Object.keys(data)) : {},
+        previousData: current ? pickFields(current, Object.keys(rawData)) : {},
         sequenceNumber,
         causalDeps: [],
-        schemaVersion
+        schemaVersion,
+        ...Object.keys(atomicOps).length > 0 ? { atomicOps } : {}
       },
       clock
     );
@@ -3168,45 +3237,123 @@ function createRouteContext(server, store) {
     );
     return run;
   }
+  async function prepareMutation(mutation, scope) {
+    let op;
+    try {
+      op = await buildRouteOperation(store, mutation);
+    } catch (error) {
+      if (error instanceof RouteMutationError) {
+        return {
+          ok: false,
+          rejection: {
+            ok: false,
+            code: error.code,
+            message: error.message,
+            retriable: isRetriableRejection(error.code)
+          }
+        };
+      }
+      throw error;
+    }
+    if (scope && !operationMatchesScopes(op, scope)) {
+      return {
+        ok: false,
+        rejection: {
+          ok: false,
+          code: "SCOPE_VIOLATION",
+          message: `Mutation on "${mutation.collection}" is outside the provided scope.`,
+          retriable: isRetriableRejection("SCOPE_VIOLATION")
+        }
+      };
+    }
+    return { ok: true, op };
+  }
+  async function commitOperation(op, collection) {
+    const result = await server.applyLocalOperation(op);
+    if (result.result !== "applied") {
+      const code = result.rejection?.code ?? "NOT_APPLIED";
+      return {
+        ok: false,
+        code,
+        message: result.rejection?.message ?? `Operation on "${collection}" was not applied (${result.result}).`,
+        // Prefer the pipeline's own classification when present; fall back
+        // to classifying the code so this stays correct if new codes appear.
+        retriable: result.rejection?.retriable ?? isRetriableRejection(code)
+      };
+    }
+    const record = await store.findRecord(collection, op.recordId);
+    return { ok: true, operation: op, record };
+  }
+  async function rawApply(mutation, scope) {
+    const prepared = await prepareMutation(mutation, scope);
+    if (!prepared.ok) {
+      return prepared.rejection;
+    }
+    return commitOperation(prepared.op, mutation.collection);
+  }
   return {
     apply(mutation, options) {
+      return serialize(() => rawApply(mutation, options?.scope));
+    },
+    applyConditional(spec, options) {
       return serialize(async () => {
-        let op;
-        try {
-          op = await buildRouteOperation(store, mutation);
-        } catch (error) {
-          if (error instanceof RouteMutationError) {
+        if (spec.idempotencyKey) {
+          const existing = await store.findRecord(
+            spec.idempotencyKey.collection,
+            spec.idempotencyKey.id
+          );
+          if (existing) {
+            return { ok: true, idempotent: true, operations: [], records: [existing] };
+          }
+        }
+        if (spec.if && Object.keys(spec.if).length > 0) {
+          const target = await store.findRecord(spec.collection, spec.id);
+          if (!evaluateRoutePredicate(target, spec.if)) {
+            const code = spec.reject?.code ?? "CONDITION_NOT_MET";
             return {
               ok: false,
-              code: error.code,
-              message: error.message,
-              retriable: isRetriableRejection(error.code)
+              code,
+              message: spec.reject?.message ?? `Admission condition not met on "${spec.collection}" record "${spec.id}".`,
+              retriable: false
             };
           }
-          throw error;
         }
-        if (options?.scope && !operationMatchesScopes(op, options.scope)) {
-          return {
-            ok: false,
-            code: "SCOPE_VIOLATION",
-            message: `Mutation on "${mutation.collection}" is outside the provided scope.`,
-            retriable: isRetriableRejection("SCOPE_VIOLATION")
-          };
+        const mutations = [];
+        if (spec.update !== void 0 && spec.update !== null) {
+          mutations.push({
+            collection: spec.collection,
+            type: "update",
+            recordId: spec.id,
+            data: spec.update
+          });
         }
-        const result = await server.applyLocalOperation(op);
-        if (result.result !== "applied") {
-          const code = result.rejection?.code ?? "NOT_APPLIED";
-          return {
-            ok: false,
-            code,
-            message: result.rejection?.message ?? `Operation on "${mutation.collection}" was not applied (${result.result}).`,
-            // Prefer the pipeline's own classification when present; fall back
-            // to classifying the code so this stays correct if new codes appear.
-            retriable: result.rejection?.retriable ?? isRetriableRejection(code)
-          };
+        if (spec.also) {
+          mutations.push(...spec.also);
+        }
+        const prepared = [];
+        for (const mutation of mutations) {
+          const p = await prepareMutation(mutation, options?.scope);
+          if (!p.ok) {
+            return p.rejection;
+          }
+          prepared.push({ op: p.op, collection: mutation.collection });
+        }
+        const operations2 = [];
+        const records = [];
+        for (const { op, collection } of prepared) {
+          const result = await commitOperation(op, collection);
+          if (!result.ok) {
+            return {
+              ok: false,
+              code: result.code,
+              message: result.message,
+              retriable: result.retriable
+            };
+          }
+          operations2.push(result.operation);
+          records.push(result.record);
         }
-        const record = await store.findRecord(mutation.collection, op.recordId);
-        return { ok: true, operation: op, record };
+        return { ok: true, idempotent: false, operations: operations2, records };
       });
     },
     async query(collection, options) {