sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ DurableObjectStorage.ts

import type * as cf from "@cloudflare/workers-types";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Pipeable from "effect/Pipeable";
import * as Scheduler from "effect/Scheduler";
import * as Stream from "effect/Stream";
import { flushDurableObjectAlarm } from "./DurableObjectAlarmStorage.ts";
import {
  ActiveStorageTransactions,
  type ActiveStorageTransaction,
} from "./DurableObjectTransactionContext.ts";

/** A native transaction failure or invalid use of a transaction's owner. */
export class DurableObjectStorageError extends Data.TaggedError("DurableObjectStorageError")<{
  readonly operation: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

// Pre-existing sibling fibers do not inherit the transaction's context.
const activeStorageTransactions = new WeakMap<cf.DurableObjectStorage, ActiveStorageTransaction>();

const checkTransactionOwner = (transaction: ActiveStorageTransaction, allowRolledBack = false) =>
  Effect.withFiber((fiber) =>
    transaction.active &&
    transaction.owner === fiber &&
    (allowRolledBack || !transaction.rolledBack)
      ? Effect.void
      : Effect.fail(
          new DurableObjectStorageError({
            operation: "transaction",
            message: !transaction.active
              ? "The storage transaction callback has already finished"
              : transaction.owner !== fiber
                ? "A storage transaction cannot be used by another fiber"
                : "The storage transaction has been rolled back",
          }),
        ),
  );

/** @internal Joins an owned transaction, or starts a native transaction. */
function withStorageTransaction<A, E, R>(
  storage: cf.DurableObjectStorage,
  effect: Effect.Effect<A, E, R>,
): Effect.Effect<A, E | DurableObjectStorageError, R>;
function withStorageTransaction<A, E, R>(
  storage: cf.DurableObjectStorage,
  closure: (txn: DurableObjectTransaction) => Effect.Effect<A, E, R>,
): Effect.Effect<A, E | DurableObjectStorageError, R>;
function withStorageTransaction<A, E, R>(
  storage: cf.DurableObjectStorage,
  body: Effect.Effect<A, E, R> | ((txn: DurableObjectTransaction) => Effect.Effect<A, E, R>),
): Effect.Effect<A, E | DurableObjectStorageError, R> {
  return Effect.gen(function* () {
    const transactions = yield* ActiveStorageTransactions;
    const existing = transactions.get(storage) ?? activeStorageTransactions.get(storage);
    const evaluate = (transaction: ActiveStorageTransaction) =>
      Effect.suspend(() =>
        typeof body === "function"
          ? body(
              makeDurableObjectTransaction(
                transaction.transaction,
                checkTransactionOwner(transaction).pipe(Effect.orDie),
                checkTransactionOwner(transaction, true).pipe(
                  Effect.andThen(() =>
                    Effect.sync(() => {
                      if (!transaction.rolledBack) {
                        transaction.transaction.rollback();
                        transaction.rolledBack = true;
                      }
                    }),
                  ),
                  Effect.orDie,
                ),
                flushDurableObjectAlarm(storage),
              ),
            )
          : body,
      );

    if (existing !== undefined) {
      yield* checkTransactionOwner(existing);
      return yield* evaluate(existing);
    }

    const context = yield* Effect.context<R>();
    // Native input gates can block timers; fiber yields must use microtasks.
    const scheduler = new Scheduler.MixedScheduler("sync");

    return yield* Effect.scoped(
      Effect.gen(function* () {
        let cancelled = false;
        let native: Promise<A> | undefined;
        let failure: Exit.Failure<A, E> | undefined;
        let currentTransaction: ActiveStorageTransaction | undefined;
        const release = () => {
          if (currentTransaction !== undefined) {
            currentTransaction.active = false;
            if (activeStorageTransactions.get(storage) === currentTransaction) {
              activeStorageTransactions.delete(storage);
            }
          }
        };

        yield* Effect.addFinalizer(
          Effect.fn(function* () {
            cancelled = true;
            // The synchronous scheduler can re-enter this finalizer before
            // runForkWith returns. The callback publishes its owner first.
            const owner = currentTransaction?.owner;
            if (owner !== undefined) {
              yield* Fiber.interrupt(owner);
            }
            const settlement = native;
            if (settlement !== undefined) {
              // The callback must finish before waiting for native rollback.
              yield* Effect.promise(() =>
                settlement.then(
                  () => undefined,
                  () => undefined,
                ),
              );
            }
          }),
        );

        return yield* Effect.callback<A, E | DurableObjectStorageError>((resume) => {
          const reject = (cause: unknown) => {
            release();
            resume(
              failure !== undefined && cause === failure
                ? Effect.failCause(failure.cause)
                : Effect.fail(
                    new DurableObjectStorageError({
                      operation: "transaction",
                      message: "The native storage transaction failed",
                      cause,
                    }),
                  ),
            );
          };

          try {
            native = storage.transaction((txn) => {
              if (cancelled) {
                throw new DurableObjectStorageError({
                  operation: "transaction",
                  message: "The storage transaction caller was interrupted",
                });
              }
              const transaction: ActiveStorageTransaction = {
                transaction: txn,
                owner: undefined,
                active: true,
                rolledBack: false,
                alarmTablesEnsured: false,
                alarmDirty: false,
              };
              currentTransaction = transaction;
              activeStorageTransactions.set(storage, transaction);
              const callbackContext = Context.add(
                context,
                ActiveStorageTransactions,
                new Map(transactions).set(storage, transaction),
              );

              return new Promise<A>((resolve, rejectCallback) => {
                const callbackFiber = Effect.runForkWith(callbackContext)(
                  Effect.withFiber((fiber) => {
                    transaction.owner = fiber;
                    return evaluate(transaction).pipe(
                      Effect.scoped,
                      Effect.tap(() => flushDurableObjectAlarm(storage)),
                    );
                  }),
                  { scheduler },
                );
                callbackFiber.addObserver((exit) => {
                  transaction.active = false;
                  if (Exit.isSuccess(exit)) {
                    resolve(exit.value);
                  } else {
                    failure = exit;
                    rejectCallback(exit);
                  }
                });
              });
            });
            native.then((value) => {
              release();
              resume(Effect.succeed(value));
            }, reject);
          } catch (cause) {
            reject(cause);
          }
        });
      }),
    );
  });
}

// ---------------------------------------------------------------------------
// SqlStorage — Effect-native wrapper around cf.SqlStorage
// ---------------------------------------------------------------------------

export type SqlStorageValue = cf.SqlStorageValue;

export interface SqlCursor<T extends Record<string, SqlStorageValue>> extends Stream.Stream<T> {
  next(): Effect.Effect<
    { done?: false; value: T } | { done: true; value?: never },
    never,
    RuntimeContext
  >;
  toArray(): Effect.Effect<T[], never, RuntimeContext>;
  one(): Effect.Effect<T, never, RuntimeContext>;
  raw<U extends SqlStorageValue[]>(): Stream.Stream<U, never, RuntimeContext>;
  readonly columnNames: string[];
  readonly rowsRead: Effect.Effect<number, never, RuntimeContext>;
  readonly rowsWritten: Effect.Effect<number, never, RuntimeContext>;
}

export interface SqlStorage {
  /**
   * The raw underlying Cloudflare SqlStorage binding.
   *
   * Use this when you need direct access for libraries that already support
   * Cloudflare Durable Object SQLite storage.
   */
  readonly raw: cf.SqlStorage;
  exec<T extends Record<string, SqlStorageValue>>(
    query: string,
    ...bindings: any[]
  ): Effect.Effect<SqlCursor<T>, never, RuntimeContext>;
  readonly databaseSize: number;
}

const defineCursorField = <A>(self: object, key: string, value: A): A => {
  Object.defineProperty(self, key, { value, enumerable: true, configurable: true, writable: true });
  return value;
};

// Writes commonly discard the cursor. Keep its Stream, bound methods, and
// statistic Effects lazy so those writes allocate only this wrapper.
class SqlCursorImpl<T extends Record<string, SqlStorageValue>>
  extends Pipeable.Class
  implements SqlCursor<T>
{
  #cursor: cf.SqlStorageCursor<T>;

  constructor(cursor: cf.SqlStorageCursor<T>) {
    super();
    this.#cursor = cursor;
  }

  get [Stream.TypeId](): Stream.VarianceStruct<T, never, never> {
    return Stream.empty[Stream.TypeId];
  }

  get channel(): Stream.Stream<T>["channel"] {
    return defineCursorField(this, "channel", Stream.toChannel(Stream.fromIterable(this.#cursor)));
  }

  get next(): SqlCursor<T>["next"] {
    const cursor = this.#cursor;
    return defineCursorField(this, "next", () => Effect.sync(() => cursor.next()));
  }

  get toArray(): SqlCursor<T>["toArray"] {
    const cursor = this.#cursor;
    return defineCursorField(this, "toArray", () => Effect.sync(() => cursor.toArray()));
  }

  get one(): SqlCursor<T>["one"] {
    const cursor = this.#cursor;
    return defineCursorField(this, "one", () => Effect.sync(() => cursor.one()));
  }

  get raw(): SqlCursor<T>["raw"] {
    const cursor = this.#cursor;
    return defineCursorField(this, "raw", <U extends SqlStorageValue[]>() =>
      Stream.fromIterableEffect(Effect.sync(() => cursor.raw<U>())),
    );
  }

  get columnNames(): string[] {
    return defineCursorField(this, "columnNames", this.#cursor.columnNames);
  }

  get rowsRead(): SqlCursor<T>["rowsRead"] {
    const cursor = this.#cursor;
    return defineCursorField(
      this,
      "rowsRead",
      Effect.sync(() => cursor.rowsRead),
    );
  }

  get rowsWritten(): SqlCursor<T>["rowsWritten"] {
    const cursor = this.#cursor;
    return defineCursorField(
      this,
      "rowsWritten",
      Effect.sync(() => cursor.rowsWritten),
    );
  }
}

const fromSqlCursor = <T extends Record<string, SqlStorageValue>>(
  cursor: cf.SqlStorageCursor<T>,
): SqlCursor<T> => new SqlCursorImpl(cursor);

const fromSqlStorage = (sql: cf.SqlStorage, checkOwner: Effect.Effect<void>): SqlStorage => ({
  raw: sql,
  exec: <T extends Record<string, SqlStorageValue>>(
    query: string,
    ...bindings: any[]
  ): Effect.Effect<SqlCursor<T>> =>
    Effect.andThen(
      checkOwner,
      Effect.sync(() => fromSqlCursor(sql.exec<T>(query, ...bindings))),
    ),
  get databaseSize() {
    return sql.databaseSize;
  },
});

// ---------------------------------------------------------------------------
// DurableObjectTransaction
// ---------------------------------------------------------------------------

export interface DurableObjectTransaction {
  get<T = unknown>(
    key: string,
    options?: cf.DurableObjectGetOptions,
  ): Effect.Effect<T | undefined, never, RuntimeContext>;
  get<T = unknown>(
    keys: string[],
    options?: cf.DurableObjectGetOptions,
  ): Effect.Effect<Map<string, T>, never, RuntimeContext>;
  list<T = unknown>(
    options?: cf.DurableObjectListOptions,
  ): Effect.Effect<Map<string, T>, never, RuntimeContext>;
  put<T>(
    key: string,
    value: T,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  put<T>(
    entries: Record<string, T>,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  delete(
    key: string,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<boolean, never, RuntimeContext>;
  delete(
    keys: string[],
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<number, never, RuntimeContext>;
  rollback(): Effect.Effect<void, never, RuntimeContext>;
  getAlarm(
    options?: cf.DurableObjectGetAlarmOptions,
  ): Effect.Effect<number | null, never, RuntimeContext>;
  setAlarm(
    scheduledTime: number | Date,
    options?: cf.DurableObjectSetAlarmOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  deleteAlarm(
    options?: cf.DurableObjectSetAlarmOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
}

// ---------------------------------------------------------------------------
// DurableObjectStorage
// ---------------------------------------------------------------------------

export interface DurableObjectStorage {
  get<T = unknown>(
    key: string,
    options?: cf.DurableObjectGetOptions,
  ): Effect.Effect<T | undefined, never, RuntimeContext>;
  get<T = unknown>(
    keys: string[],
    options?: cf.DurableObjectGetOptions,
  ): Effect.Effect<Map<string, T>, never, RuntimeContext>;
  list<T = unknown>(
    options?: cf.DurableObjectListOptions,
  ): Effect.Effect<Map<string, T>, never, RuntimeContext>;
  put<T>(
    key: string,
    value: T,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  put<T>(
    entries: Record<string, T>,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  delete(
    key: string,
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<boolean, never, RuntimeContext>;
  delete(
    keys: string[],
    options?: cf.DurableObjectPutOptions,
  ): Effect.Effect<number, never, RuntimeContext>;
  deleteAll(options?: cf.DurableObjectPutOptions): Effect.Effect<void, never, RuntimeContext>;
  /**
   * Run an Effect inside a native storage transaction with the caller's context.
   * On SQLite-backed storage, SQL, KV, and alarm writes to this storage commit
   * together. Typed failures, defects, and interruption roll back the transaction.
   * Interruption waits for the callback fiber and native rollback to finish.
   * Nested calls on the same fiber join the active transaction; transaction
   * handles cannot be used by another fiber or after the callback finishes.
   */
  transaction<A, E = never, R = never>(
    effect: Effect.Effect<A, E, R>,
  ): Effect.Effect<A, E | DurableObjectStorageError, R | RuntimeContext>;
  transaction<A, E = never, R = never>(
    closure: (txn: DurableObjectTransaction) => Effect.Effect<A, E, R>,
  ): Effect.Effect<A, E | DurableObjectStorageError, R | RuntimeContext>;
  getAlarm(
    options?: cf.DurableObjectGetAlarmOptions,
  ): Effect.Effect<number | null, never, RuntimeContext>;
  setAlarm(
    scheduledTime: number | Date,
    options?: cf.DurableObjectSetAlarmOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  deleteAlarm(
    options?: cf.DurableObjectSetAlarmOptions,
  ): Effect.Effect<void, never, RuntimeContext>;
  sync(): Effect.Effect<void, never, RuntimeContext>;
  sql: SqlStorage;
  kv: cf.SyncKvStorage;
  getCurrentBookmark(): Effect.Effect<string, never, RuntimeContext>;
  getBookmarkForTime(timestamp: number | Date): Effect.Effect<string, never, RuntimeContext>;
  onNextSessionRestoreBookmark(bookmark: string): Effect.Effect<string, never, RuntimeContext>;
}

// ---------------------------------------------------------------------------
// Constructors from raw Cloudflare types
// ---------------------------------------------------------------------------

export const fromDurableObjectTransaction = (
  txn: cf.DurableObjectTransaction,
): DurableObjectTransaction => makeDurableObjectTransaction(txn, Effect.void);

const makeDurableObjectTransaction = (
  txn: cf.DurableObjectTransaction,
  checkOwner: Effect.Effect<void>,
  rollback = Effect.andThen(
    checkOwner,
    Effect.sync(() => txn.rollback()),
  ),
  flushAlarm: Effect.Effect<void> = Effect.void,
): DurableObjectTransaction => {
  const use = <A>(effect: Effect.Effect<A>) => Effect.andThen(checkOwner, effect);
  const useAlarm = <A>(effect: Effect.Effect<A>) => use(Effect.andThen(flushAlarm, effect));

  return {
    get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) =>
      use(Effect.promise(() => txn.get(keyOrKeys as any, options)))) as any,
    list: (options?: cf.DurableObjectListOptions) => use(Effect.promise(() => txn.list(options))),
    put: ((
      keyOrEntries: string | Record<string, unknown>,
      valueOrOptions?: unknown,
      maybeOptions?: cf.DurableObjectPutOptions,
    ) =>
      use(
        typeof keyOrEntries === "string"
          ? Effect.promise(() => txn.put(keyOrEntries, valueOrOptions, maybeOptions))
          : Effect.promise(() =>
              txn.put(keyOrEntries, valueOrOptions as cf.DurableObjectPutOptions | undefined),
            ),
      )) as any,
    delete: ((keyOrKeys: string | string[], options?: cf.DurableObjectPutOptions) =>
      use(Effect.promise(() => txn.delete(keyOrKeys as any, options)))) as any,
    rollback: () => rollback,
    getAlarm: (options?: cf.DurableObjectGetAlarmOptions) =>
      useAlarm(Effect.promise(() => txn.getAlarm(options))),
    setAlarm: (scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions) =>
      useAlarm(Effect.promise(() => txn.setAlarm(scheduledTime, options))),
    deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) =>
      useAlarm(Effect.promise(() => txn.deleteAlarm(options))),
  };
};

export const fromDurableObjectStorage = (
  storage: cf.DurableObjectStorage,
): DurableObjectStorage => {
  const checkOwner = Effect.withFiber((fiber) => {
    const transaction =
      fiber.getRef(ActiveStorageTransactions).get(storage) ??
      activeStorageTransactions.get(storage);
    return transaction === undefined
      ? Effect.void
      : checkTransactionOwner(transaction).pipe(Effect.orDie);
  });
  const use = <A>(effect: Effect.Effect<A>) => Effect.andThen(checkOwner, effect);
  const useAlarm = <A>(effect: Effect.Effect<A>) =>
    use(Effect.andThen(flushDurableObjectAlarm(storage), effect));

  return {
    get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) =>
      use(Effect.promise(() => storage.get(keyOrKeys as any, options)))) as any,
    list: (options?: cf.DurableObjectListOptions) =>
      use(Effect.promise(() => storage.list(options))),
    put: ((
      keyOrEntries: string | Record<string, unknown>,
      valueOrOptions?: unknown,
      maybeOptions?: cf.DurableObjectPutOptions,
    ) =>
      use(
        typeof keyOrEntries === "string"
          ? Effect.promise(() => storage.put(keyOrEntries, valueOrOptions, maybeOptions))
          : Effect.promise(() =>
              storage.put(keyOrEntries, valueOrOptions as cf.DurableObjectPutOptions | undefined),
            ),
      )) as any,
    delete: ((keyOrKeys: string | string[], options?: cf.DurableObjectPutOptions) =>
      use(Effect.promise(() => storage.delete(keyOrKeys as any, options)))) as any,
    deleteAll: (options?: cf.DurableObjectPutOptions) =>
      use(Effect.promise(() => storage.deleteAll(options))),
    transaction: <A, E, R>(
      body: Effect.Effect<A, E, R> | ((txn: DurableObjectTransaction) => Effect.Effect<A, E, R>),
    ) => withStorageTransaction(storage, (txn) => (typeof body === "function" ? body(txn) : body)),
    getAlarm: (options?: cf.DurableObjectGetAlarmOptions) =>
      useAlarm(Effect.promise(() => storage.getAlarm(options))),
    setAlarm: (scheduledTime: number | Date, options?: cf.DurableObjectSetAlarmOptions) =>
      useAlarm(Effect.promise(() => storage.setAlarm(scheduledTime, options))),
    deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) =>
      useAlarm(Effect.promise(() => storage.deleteAlarm(options))),
    sync: () => use(Effect.promise(() => storage.sync())),
    sql: fromSqlStorage(storage.sql, checkOwner),
    kv: storage.kv,
    getCurrentBookmark: () => use(Effect.promise(() => storage.getCurrentBookmark())),
    getBookmarkForTime: (timestamp: number | Date) =>
      use(Effect.promise(() => storage.getBookmarkForTime(timestamp))),
    onNextSessionRestoreBookmark: (bookmark: string) =>
      use(Effect.promise(() => storage.onNextSessionRestoreBookmark(bookmark))),
  };
};