@beignet/provider-db-drizzle 0.0.9

package/src/shared/rows.ts

@@ -0,0 +1,197 @@
+/**
+ * Shared row encode/decode helpers for Drizzle database providers.
+ *
+ * Every dialect stores timestamps as ISO-8601 UTC strings in `text` columns.
+ * This is deliberate: lexicographic order equals chronological order, the
+ * storage semantics stay byte-identical across SQLite, Postgres, and MySQL,
+ * and all values route through this single encode/decode point so a dialect
+ * could later move to native timestamp types without touching the shared
+ * orchestration in `outbox-core.ts` and `idempotency-core.ts`.
+ */
+
+import type { IdempotencyReservation } from "@beignet/core/idempotency";
+import {
+  type ClaimedOutboxMessage,
+  OutboxClaimError,
+  type OutboxErrorInfo,
+  type OutboxJsonValue,
+  type OutboxMessage,
+  type OutboxMessageKind,
+  type OutboxMessageStatus,
+} from "@beignet/core/outbox";
+
+/**
+ * Encode a timestamp for storage. All dialects store ISO-8601 UTC strings.
+ */
+export function encodeTimestamp(value: Date): string {
+  return value.toISOString();
+}
+
+/**
+ * Decode a stored timestamp string back into a `Date`.
+ */
+export function decodeTimestamp(value: string): Date {
+  return new Date(value);
+}
+
+/**
+ * Decode a nullable stored timestamp string.
+ */
+export function parseNullableDate(value: string | null): Date | null {
+  return value ? decodeTimestamp(value) : null;
+}
+
+/**
+ * Decode a stored outbox error JSON column.
+ */
+export function parseLastError(value: string | null): OutboxErrorInfo | null {
+  return value ? (JSON.parse(value) as OutboxErrorInfo) : null;
+}
+
+/**
+ * Raw outbox table row shape shared by every dialect.
+ */
+export interface OutboxRow {
+  id: string;
+  kind: OutboxMessageKind;
+  name: string;
+  payload_json: string;
+  status: OutboxMessageStatus;
+  attempts: number;
+  max_attempts: number;
+  available_at: string;
+  claimed_at: string | null;
+  locked_until: string | null;
+  claim_token: string | null;
+  delivered_at: string | null;
+  last_error_json: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/**
+ * Decode a raw outbox row into an `OutboxMessage`.
+ */
+export function rowToMessage(row: OutboxRow): OutboxMessage {
+  return {
+    id: row.id,
+    kind: row.kind,
+    name: row.name,
+    payload: JSON.parse(row.payload_json) as OutboxJsonValue,
+    status: row.status,
+    attempts: row.attempts,
+    maxAttempts: row.max_attempts,
+    availableAt: decodeTimestamp(row.available_at),
+    claimedAt: parseNullableDate(row.claimed_at),
+    lockedUntil: parseNullableDate(row.locked_until),
+    claimToken: row.claim_token,
+    deliveredAt: parseNullableDate(row.delivered_at),
+    lastError: parseLastError(row.last_error_json),
+    createdAt: decodeTimestamp(row.created_at),
+    updatedAt: decodeTimestamp(row.updated_at),
+  };
+}
+
+/**
+ * Decode a raw outbox row into a `ClaimedOutboxMessage`.
+ *
+ * @throws OutboxClaimError when the row is not in a fully claimed state.
+ */
+export function rowToClaimedMessage(row: OutboxRow): ClaimedOutboxMessage {
+  const message = rowToMessage(row);
+  if (
+    message.status !== "claimed" ||
+    !message.claimToken ||
+    !message.claimedAt ||
+    !message.lockedUntil
+  ) {
+    throw new OutboxClaimError({
+      id: message.id,
+      message: `Outbox message "${message.id}" is not claimed.`,
+    });
+  }
+
+  return {
+    ...message,
+    status: "claimed",
+    claimToken: message.claimToken,
+    claimedAt: message.claimedAt,
+    lockedUntil: message.lockedUntil,
+  };
+}
+
+/**
+ * Stored idempotency record status values shared by every dialect.
+ */
+export type IdempotencyRowStatus = "in-progress" | "completed";
+
+/**
+ * Raw idempotency table row shape shared by every dialect.
+ */
+export interface IdempotencyRow {
+  storage_key: string;
+  namespace: string;
+  idempotency_key: string;
+  scope_key: string;
+  fingerprint: string;
+  status: IdempotencyRowStatus;
+  result_json: string | null;
+  reserved_at: string;
+  completed_at: string | null;
+  expires_at: string | null;
+  updated_at: string;
+}
+
+/**
+ * Decode a raw idempotency row into the reservation outcome for a caller
+ * holding `receivedFingerprint`.
+ */
+export function idempotencyReservationFromRow(
+  row: IdempotencyRow,
+  receivedFingerprint: string,
+): IdempotencyReservation {
+  const reservedAt = decodeTimestamp(row.reserved_at);
+  const completedAt = parseNullableDate(row.completed_at);
+  const expiresAt = parseNullableDate(row.expires_at);
+
+  if (row.fingerprint !== receivedFingerprint) {
+    return {
+      status: "conflict",
+      namespace: row.namespace,
+      key: row.idempotency_key,
+      scopeKey: row.scope_key,
+      storedFingerprint: row.fingerprint,
+      receivedFingerprint,
+      reservedAt,
+      completedAt: completedAt ?? undefined,
+      expiresAt,
+    };
+  }
+
+  if (row.status === "completed" && completedAt) {
+    return {
+      status: "replay",
+      namespace: row.namespace,
+      key: row.idempotency_key,
+      scopeKey: row.scope_key,
+      fingerprint: row.fingerprint,
+      result:
+        row.result_json === null
+          ? undefined
+          : (JSON.parse(row.result_json) as unknown),
+      reservedAt,
+      completedAt,
+      expiresAt,
+    };
+  }
+
+  return {
+    status: "inProgress",
+    namespace: row.namespace,
+    key: row.idempotency_key,
+    scopeKey: row.scope_key,
+    fingerprint: row.fingerprint,
+    reservedAt,
+    expiresAt,
+  };
+}