alchemy 0.45.5 → 0.46.0

package/src/state/file-system-state-store.ts

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ResourceScope } from "../resource.ts";
+import type { Scope } from "../scope.ts";
+import { deserialize, serialize } from "../serde.ts";
+import type { State, StateStore } from "../state.ts";
+import { ignore } from "../util/ignore.ts";
+
+const stateRootDir = path.join(process.cwd(), ".alchemy");
+const ALCHEMY_SEPERATOR_CHAR = process.platform === "win32" ? "-" : ":";
+
+export class FileSystemStateStore implements StateStore {
+  public readonly dir: string;
+  private initialized = false;
+  constructor(
+    public readonly scope: Scope,
+    options?: {
+      rootDir?: string;
+    },
+  ) {
+    this.dir = path.join(options?.rootDir ?? stateRootDir, ...scope.chain);
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    await fs.promises.mkdir(this.dir, { recursive: true });
+  }
+
+  async deinit(): Promise<void> {
+    await ignore("ENOENT", async () => {
+      const entries = await fs.promises.readdir(this.dir, {
+        withFileTypes: true,
+      });
+      const files = entries.filter((entry) => entry.isFile());
+      if (files.length > 0) {
+        throw new Error(
+          `Cannot deinit: directory "${this.dir}" contains files and cannot be deleted.`,
+        );
+      }
+      // Only folders (or empty), delete recursively
+      await fs.promises.rm(this.dir, { recursive: true, force: true });
+    });
+  }
+
+  async count(): Promise<number> {
+    return Object.keys(await this.list()).length;
+  }
+
+  async list(): Promise<string[]> {
+    try {
+      const files = await fs.promises.readdir(this.dir, {
+        withFileTypes: true,
+      });
+      return files
+        .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
+        .map((dirent) => dirent.name.replace(/\.json$/, ""))
+        .map((key) => key.replaceAll(":", "/"));
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  async get(key: string): Promise<State | undefined> {
+    try {
+      const content = await fs.promises.readFile(this.getPath(key), "utf8");
+      const state = (await deserialize(
+        this.scope,
+        JSON.parse(content),
+      )) as State;
+      if (state.output === undefined) {
+        state.output = {} as any;
+      }
+      state.output[ResourceScope] = this.scope;
+      return state;
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async set(key: string, value: State): Promise<void> {
+    await this.init();
+    const file = this.getPath(key);
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(
+      file,
+      JSON.stringify(await serialize(this.scope, value), null, 2),
+    );
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      return await fs.promises.unlink(this.getPath(key));
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  async all(): Promise<Record<string, State>> {
+    return this.getBatch(await this.list());
+  }
+
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    return Object.fromEntries(
+      (
+        await Promise.all(
+          Array.from(ids).flatMap(async (id) => {
+            const s = await this.get(id);
+            if (s === undefined) {
+              return [] as const;
+            }
+            return [[id, s]] as const;
+          }),
+        )
+      ).flat(),
+    );
+  }
+
+  private getPath(key: string): string {
+    if (key.includes(":")) {
+      throw new Error(`ID cannot include colons: ${key}`);
+    }
+    if (key.includes("/")) {
+      //todo(michael): remove this next time we do a breaking change
+      //* windows doesn't support ":" in file paths, but we already use ":"
+      //* so now we use both to prevent breaking changes
+      key = key.replaceAll("/", ALCHEMY_SEPERATOR_CHAR);
+    }
+    //todo(michael): remove this next time we do a breaking change
+    //* windows doesn't support "*" in file paths, but we already use "*"
+    //* when making cloudflare routes containing "*"
+    //* so now we use "+" on windows but "*" on mac/linux to prevent breaking changes
+    if (process.platform === "win32") {
+      key = key.replaceAll("*", "+");
+    }
+    return path.join(this.dir, `${key}.json`);
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,6 @@
+export * from "./cloudflare-state-store.ts";
+export * from "./d1-state-store.ts";
+export * from "./dofs-state-store/index.ts";
+export * from "./file-system-state-store.ts";
+export * from "./r2-rest-state-store.ts";
+export * from "./sqlite-state-store.ts";

package/src/state/migrations.ts

@@ -0,0 +1,9 @@
+import path from "node:path";
+
+export const MIGRATIONS_DIRECTORY = path.join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "drizzle",
+  "default",
+);

package/src/state/operations.ts

@@ -0,0 +1,152 @@
+import { and, eq, getTableColumns, inArray } from "drizzle-orm";
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+import type { State, StateStore } from "../state.ts";
+import { assertNever } from "../util/assert-never.ts";
+import type { StateStoreProxy } from "./proxy.ts";
+import * as schema from "./schema.ts";
+
+const { scope: _, ...columns } = getTableColumns(schema.resources);
+
+type Database = BaseSQLiteDatabase<any, any, typeof schema>;
+
+/**
+ * Represents the SQL operations for a SQLite-backed state store.
+ * DOES NOT include serialization/deserialization — that is handled by the `StateStoreProxy` class.
+ */
+export class SQLiteStateStoreOperations implements StateStore {
+  constructor(
+    private readonly db: Database,
+    private readonly context: { chain: string[] },
+  ) {}
+
+  async dispatch<TMethod extends StateStoreProxy.Method>(
+    method: TMethod,
+    params: StateStoreProxy.API[TMethod]["params"],
+  ): Promise<StateStoreProxy.API[TMethod]["result"]> {
+    switch (method) {
+      case "init":
+        return;
+      case "deinit":
+        return;
+      case "list":
+        return this.list();
+      case "count":
+        return this.count();
+      case "get": {
+        const [key] = params as StateStoreProxy.API["get"]["params"];
+        return this.get(key);
+      }
+      case "getBatch": {
+        const [keys] = params as StateStoreProxy.API["getBatch"]["params"];
+        return this.getBatch(keys);
+      }
+      case "all":
+        return this.all();
+      case "set": {
+        const [key, state] = params as StateStoreProxy.API["set"]["params"];
+        return this.set(key, state);
+      }
+      case "delete": {
+        const [key] = params as StateStoreProxy.API["delete"]["params"];
+        return this.delete(key);
+      }
+      default:
+        assertNever(method);
+    }
+  }
+
+  async list() {
+    const result = await this.db
+      .select({ id: schema.resources.id })
+      .from(schema.resources)
+      .where(eq(schema.resources.scope, this.context.chain));
+    return result.map((r) => r.id);
+  }
+  async count() {
+    const result = await this.db.$count(
+      this.db
+        .select()
+        .from(schema.resources)
+        .where(eq(schema.resources.scope, this.context.chain)),
+    );
+    return result;
+  }
+  async get(key: string) {
+    const [result] = await this.db
+      .select(columns)
+      .from(schema.resources)
+      .where(
+        and(
+          eq(schema.resources.scope, this.context.chain),
+          eq(schema.resources.id, key),
+        ),
+      );
+    if (!result) {
+      return undefined;
+    }
+    return {
+      ...result,
+      props: result.props ?? undefined,
+      oldProps: result.oldProps ?? undefined,
+    };
+  }
+  async all() {
+    const result = await this.db
+      .select(columns)
+      .from(schema.resources)
+      .where(eq(schema.resources.scope, this.context.chain));
+    const record: Record<string, State> = {};
+    for (const r of result) {
+      record[r.id] = {
+        ...r,
+        props: r.props ?? undefined,
+        oldProps: r.oldProps ?? undefined,
+      };
+    }
+    return record;
+  }
+  async set(_key: string, state: State) {
+    await this.db
+      .insert(schema.resources)
+      .values({
+        ...state,
+        scope: this.context.chain,
+      })
+      .onConflictDoUpdate({
+        target: [schema.resources.id, schema.resources.scope],
+        set: {
+          ...state,
+        },
+      });
+  }
+  async delete(key: string) {
+    await this.db
+      .delete(schema.resources)
+      .where(
+        and(
+          eq(schema.resources.scope, this.context.chain),
+          eq(schema.resources.id, key),
+        ),
+      );
+  }
+  async getBatch(keys: string[]) {
+    const result = await this.db
+      .select(columns)
+      .from(schema.resources)
+      .where(
+        and(
+          eq(schema.resources.scope, this.context.chain),
+          inArray(schema.resources.id, keys),
+        ),
+      );
+    const record: Record<string, State> = {};
+    for (const r of result) {
+      record[r.id] = {
+        ...r,
+        props: r.props ?? undefined,
+        oldProps: r.oldProps ?? undefined,
+      };
+    }
+    return record;
+  }
+}

package/src/state/proxy.ts

@@ -0,0 +1,132 @@
+import type { Scope } from "../scope.ts";
+import type { State, StateStore } from "../state.ts";
+import { withExponentialBackoff } from "../util/retry.ts";
+
+/**
+ * Wraps a local or remote state store implementation
+ * and handles serialization/deserialization.
+ */
+export abstract class StateStoreProxy implements StateStore {
+  private dispatch?: Promise<StateStoreProxy.Dispatch>;
+
+  constructor(readonly scope: Scope) {}
+
+  abstract provision(): Promise<StateStoreProxy.Dispatch>;
+
+  private async run<TMethod extends StateStoreProxy.Method>(
+    method: TMethod,
+    params: StateStoreProxy.API[TMethod]["params"],
+  ): Promise<StateStoreProxy.API[TMethod]["result"]> {
+    this.dispatch ??= this.provision();
+    return this.dispatch.then(async (dispatch) => {
+      const result = await withExponentialBackoff(
+        () => dispatch(method, params),
+        () => true,
+      );
+      return result;
+    });
+  }
+
+  init(): Promise<void> {
+    return this.run("init", []);
+  }
+
+  deinit(): Promise<void> {
+    return this.run("deinit", []);
+  }
+
+  list(): Promise<string[]> {
+    return this.run("list", []);
+  }
+
+  count(): Promise<number> {
+    return this.run("count", []);
+  }
+
+  async get(key: string): Promise<State | undefined> {
+    const result = await this.run("get", [key]);
+    if (result === undefined) {
+      return undefined;
+    }
+    return await this.deserialize(result);
+  }
+
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    return this.deserializeMany(await this.run("getBatch", [ids]));
+  }
+
+  async all(): Promise<Record<string, State>> {
+    return this.deserializeMany(await this.run("all", []));
+  }
+
+  async set(key: string, value: State): Promise<void> {
+    return this.run("set", [key, await this.serialize(value)]);
+  }
+
+  async delete(key: string): Promise<void> {
+    return this.run("delete", [key]);
+  }
+
+  private async deserialize(state: State): Promise<State> {
+    const { deserialize } = await import("../serde.ts"); // dynamic import to avoid circular dependency
+    return await deserialize(this.scope, state);
+  }
+
+  private async serialize(state: State) {
+    const { serialize } = await import("../serde.ts");
+    return await serialize(this.scope, state);
+  }
+
+  private async deserializeMany(states: Record<string, State>) {
+    return Object.fromEntries(
+      await Promise.all(
+        Object.entries(states).map(async ([key, value]) => [
+          key,
+          await this.deserialize(value),
+        ]),
+      ),
+    );
+  }
+}
+
+export declare namespace StateStoreProxy {
+  export type API = {
+    [K in keyof Required<StateStore>]: NonNullable<StateStore[K]> extends (
+      ...args: infer Args
+    ) => Promise<infer Return>
+      ? {
+          method: K;
+          params: Args;
+          result: Return;
+        }
+      : never;
+  };
+  export type Method = keyof API;
+
+  export type Dispatch = <TMethod extends Method>(
+    method: TMethod,
+    params: API[TMethod]["params"],
+  ) => Promise<API[TMethod]["result"]>;
+
+  export type Request<TMethod extends Method, TContext = unknown> = {
+    method: TMethod;
+    params: API[TMethod]["params"];
+    context: TContext;
+  };
+
+  export type SuccessResponse<TMethod extends Method> = {
+    success: true;
+    status: number;
+    result: API[TMethod]["result"];
+  };
+
+  export type ErrorResponse = {
+    success: false;
+    status: number;
+    error: string;
+  };
+
+  export type Response<TMethod extends Method> =
+    | SuccessResponse<TMethod>
+    | ErrorResponse;
+}

package/src/{cloudflare → state}/r2-rest-state-store.ts

@@ -1,15 +1,14 @@
-import { ResourceScope } from "../resource.ts";
-import type { Scope } from "../scope.ts";
-import { serialize, deserialize } from "../serde.ts";
-import type { State, StateStore } from "../state.ts";
-import { withExponentialBackoff } from "../util/retry.ts";
-import { CloudflareApiError, handleApiError } from "./api-error.ts";
+import { CloudflareApiError, handleApiError } from "../cloudflare/api-error.ts";
 import {
   type CloudflareApi,
   type CloudflareApiOptions,
   createCloudflareApi,
-} from "./api.ts";
-import { createBucket, getBucket } from "./bucket.ts";
+} from "../cloudflare/api.ts";
+import { ResourceScope } from "../resource.ts";
+import type { Scope } from "../scope.ts";
+import { deserialize, serialize } from "../serde.ts";
+import type { State, StateStore } from "../state.ts";
+import { withExponentialBackoff } from "../util/retry.ts";
 
 /**
  * Options for CloudflareR2StateStore
@@ -31,6 +30,8 @@ export interface CloudflareR2StateStoreOptions extends CloudflareApiOptions {
 /**
  * State store implementation using Cloudflare R2 API
  * Uses R2 for immediate consistency compared to KV's eventual consistency
+ *
+ * @deprecated Use `CloudflareStateStore` from `alchemy/state` instead.
  */
 export class R2RestStateStore implements StateStore {
   private api: CloudflareApi;
@@ -66,6 +67,8 @@ export class R2RestStateStore implements StateStore {
   async init(): Promise<void> {
     if (this.initialized) return;
 
+    const { createBucket, getBucket } = await import("../cloudflare/bucket.ts");
+
     // Create Cloudflare API client with automatic account discovery
     this.api = await createCloudflareApi(this.options);
 

package/src/{sqlite → state}/sqlite-state-store.ts

@@ -3,10 +3,9 @@ import fs from "node:fs";
 import path from "node:path";
 import type { Scope } from "../scope.ts";
 import { memoize } from "../util/memoize.ts";
-import {
-  BaseSQLiteStateStore,
-  resolveMigrationsPath,
-} from "./base-sqlite-state-store.ts";
+import { MIGRATIONS_DIRECTORY } from "./migrations.ts";
+import { SQLiteStateStoreOperations } from "./operations.ts";
+import { StateStoreProxy } from "./proxy.ts";
 import * as schema from "./schema.ts";
 
 interface BunSQLiteStateStoreOptions {
@@ -73,11 +72,20 @@ type SQLiteStateStoreOptions =
   | LibSQLStateStoreOptions
   | AutoSQLiteStateStoreOptions;
 
-export class SQLiteStateStore extends BaseSQLiteStateStore {
-  constructor(scope: Scope, options?: SQLiteStateStoreOptions) {
-    super(scope, {
-      create: async () => createDatabase(options),
+export class SQLiteStateStore extends StateStoreProxy {
+  constructor(
+    scope: Scope,
+    private options?: SQLiteStateStoreOptions,
+  ) {
+    super(scope);
+  }
+
+  async provision(): Promise<StateStoreProxy.Dispatch> {
+    const db = await createDatabase(this.options);
+    const operations = new SQLiteStateStoreOperations(db, {
+      chain: this.scope.chain,
     });
+    return operations.dispatch.bind(operations);
   }
 }
 
@@ -132,7 +140,7 @@ async function createBunSQLiteDatabase(
   const db = drizzle(client, {
     schema,
   });
-  migrate(db, { migrationsFolder: resolveMigrationsPath() });
+  migrate(db, { migrationsFolder: MIGRATIONS_DIRECTORY });
   return db;
 }
 
@@ -162,7 +170,7 @@ async function createLibSQLDatabase(
   const db = drizzle(client, {
     schema,
   });
-  await migrate(db, { migrationsFolder: resolveMigrationsPath() });
+  await migrate(db, { migrationsFolder: MIGRATIONS_DIRECTORY });
   return db;
 }
 

package/src/test/vitest.ts

@@ -1,12 +1,14 @@
 import path from "node:path";
 import { afterAll, beforeAll, it } from "vitest";
 import { alchemy } from "../alchemy.ts";
-import { D1StateStore } from "../cloudflare/d1-state-store.ts";
-import { DOStateStore } from "../cloudflare/do-state-store/index.ts";
-import { FileSystemStateStore } from "../fs/file-system-state-store.ts";
 import { Scope } from "../scope.ts";
-import { SQLiteStateStore } from "../sqlite/sqlite-state-store.ts";
 import type { StateStoreType } from "../state.ts";
+import {
+  CloudflareStateStore,
+  D1StateStore,
+  FileSystemStateStore,
+  SQLiteStateStore,
+} from "../state/index.ts";
 import { NoopTelemetryClient } from "../util/telemetry/client.ts";
 
 /**
@@ -129,8 +131,8 @@ export function test(
   defaultOptions.stateStore ??= (scope) => {
     const storeType = process.env.ALCHEMY_STATE_STORE;
     switch (storeType) {
-      case "dofs":
-        return new DOStateStore(scope);
+      case "do":
+        return new CloudflareStateStore(scope);
       case "fs":
         return new FileSystemStateStore(scope);
       case "d1":

package/src/util/detect-node-runtime.ts

@@ -0,0 +1,12 @@
+declare var Deno: any;
+declare var Bun: any;
+
+export type Runtime = "bun" | "deno" | "node";
+
+export function detectRuntime(): Runtime {
+  if (typeof Bun !== "undefined" && Bun !== null) return "bun";
+  if (typeof Deno !== "undefined" && Deno !== null) return "deno";
+  if (typeof process !== "undefined" && process.release?.name === "node")
+    return "node";
+  return "node";
+}

package/src/util/detect-package-manager.ts

@@ -1,18 +1,31 @@
-import fs from "node:fs";
+import { exists } from "./exists.ts";
 
-export type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
+export type PackageManager = "bun" | "pnpm" | "yarn" | "npm" | "deno";
 
-export function detectPackageManager(): PackageManager {
-  if (fs.existsSync("bun.lockb")) return "bun";
-  if (fs.existsSync("pnpm-lock.yaml")) return "pnpm";
-  if (fs.existsSync("yarn.lock")) return "yarn";
+export async function detectPackageManager(
+  path: string = process.cwd(),
+): Promise<PackageManager> {
+  if (await exists(`${path}/deno.lock`)) return "deno";
+  if (
+    (await exists(`${path}/deno.json`)) ||
+    (await exists(`${path}/deno.jsonc`))
+  )
+    return "deno";
+  if (await exists(`${path}/bun.lockb`)) return "bun";
+  if (await exists(`${path}/pnpm-lock.yaml`)) return "pnpm";
+  if (await exists(`${path}/yarn.lock`)) return "yarn";
 
   if (process.env.npm_execpath?.includes("bun")) {
     return "bun";
   }
 
+  if (process.env.DENO) {
+    return "deno";
+  }
+
   const userAgent = process.env.npm_config_user_agent;
   if (userAgent) {
+    if (userAgent.startsWith("deno")) return "deno";
     if (userAgent.startsWith("bun")) return "bun";
     if (userAgent.startsWith("pnpm")) return "pnpm";
     if (userAgent.startsWith("yarn")) return "yarn";

package/src/{cloudflare/miniflare → util}/http-server.ts

@@ -1,7 +1,7 @@
 import http from "node:http";
 import type { AddressInfo } from "node:net";
 import { Readable } from "node:stream";
-import { promiseWithResolvers } from "../../util/promise-with-resolvers.ts";
+import { promiseWithResolvers } from "./promise-with-resolvers.ts";
 
 export class HTTPServer {
   server: http.Server;

package/src/util/memoize.ts

@@ -24,12 +24,23 @@ export function memoize<F extends (...args: any[]) => Promise<any>>(
   };
 }
 
-const defaultKeyFn = (...args: any[]) => {
-  const hash = createHash("sha256");
-  args.forEach((arg) => {
-    if (arg) {
-      hash.update(JSON.stringify(arg));
+export function memoizeSync<F extends (...args: any[]) => any>(
+  fn: F,
+  keyFn: (...args: Parameters<F>) => string = defaultKeyFn,
+) {
+  const cache = new Map<string, ReturnType<F>>();
+  return (...args: Parameters<F>): ReturnType<F> => {
+    const key = keyFn(...args);
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
     }
-  });
-  return hash.digest("hex");
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+}
+
+export const defaultKeyFn = (...args: any[]) => {
+  return createHash("sha256").update(JSON.stringify(args)).digest("hex");
 };