alchemy 0.44.3 → 0.45.0

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

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ResourceScope } from "../resource.ts";
 import type { Scope } from "../scope.ts";
-import { serialize, deserialize } from "../serde.ts";
+import { deserialize, serialize } from "../serde.ts";
 import type { State, StateStore } from "../state.ts";
 import { ignore } from "../util/ignore.ts";
 

package/src/scope.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import util from "node:util";
 import type { Phase } from "./alchemy.ts";
+import { D1StateStore } from "./cloudflare/d1-state-store.ts";
 import { DOStateStore } from "./cloudflare/do-state-store/index.ts";
 import { destroy, destroyAll } from "./destroy.ts";
 import { FileSystemStateStore } from "./fs/file-system-state-store.ts";
@@ -38,7 +39,7 @@ export interface ScopeOptions {
   stateStore?: StateStoreType;
   quiet?: boolean;
   phase?: Phase;
-  dev?: boolean;
+  dev?: "prefer-local" | "prefer-remote";
   telemetryClient?: ITelemetryClient;
   logger?: LoggerApi;
 }
@@ -107,7 +108,7 @@ export class Scope {
   public readonly stateStore: StateStoreType;
   public readonly quiet: boolean;
   public readonly phase: Phase;
-  public readonly dev?: boolean;
+  public readonly dev?: "prefer-local" | "prefer-remote";
   public readonly logger: LoggerApi;
   public readonly telemetryClient: ITelemetryClient;
   public readonly dataMutex: AsyncMutex;
@@ -162,21 +163,16 @@ export class Scope {
           options.logger,
         );
 
-    this.dev = options.dev ?? this.parent?.dev ?? false;
+    this.dev = options.dev ?? this.parent?.dev;
 
     if (this.dev) {
       this.logger.warnOnce(
-        "Local development mode is in beta. Please report any issues to https://github.com/sam-goodwin/alchemy/issues.",
+        "Development mode is in beta. Please report any issues to https://github.com/sam-goodwin/alchemy/issues.",
       );
     }
 
     this.stateStore =
-      options.stateStore ??
-      this.parent?.stateStore ??
-      ((scope) =>
-        process.env.ALCHEMY_STATE_STORE === "cloudflare"
-          ? new DOStateStore(scope)
-          : new FileSystemStateStore(scope));
+      options.stateStore ?? this.parent?.stateStore ?? defaultStateStore;
     this.state = this.stateStore(this);
     if (!options.telemetryClient && !this.parent?.telemetryClient) {
       throw new Error("Telemetry client is required");
@@ -206,11 +202,23 @@ export class Scope {
   }
 
   public get chain(): string[] {
+    // Since the root scope name is the same as the app name, this ensures
+    // the root scope chain is "<app-name>" instead of "<app-name>/<app-name>".
+    if (
+      !this.parent &&
+      this.appName &&
+      this.scopeName &&
+      this.appName === this.scopeName
+    ) {
+      return [this.appName];
+    }
+
     const thisScope = this.scopeName ? [this.scopeName] : [];
-    const app = this.appName ? [this.appName] : [];
     if (this.parent) {
       return [...this.parent.chain, ...thisScope];
     }
+
+    const app = this.appName ? [this.appName] : [];
     return [...app, ...thisScope];
   }
 
@@ -489,6 +497,17 @@ export class Scope {
   }
 }
 
+const defaultStateStore: StateStoreType = (scope: Scope) => {
+  switch (process.env.ALCHEMY_STATE_STORE) {
+    case "cloudflare-d1":
+      return new D1StateStore(scope);
+    case "cloudflare":
+      return new DOStateStore(scope);
+    default:
+      return new FileSystemStateStore(scope);
+  }
+};
+
 declare global {
   // for runtime
   // TODO(sam): maybe inject is a better way to achieve this

package/src/serde.ts

@@ -5,7 +5,7 @@ import {
   ResourceKind,
   type Resource,
 } from "./resource.ts";
-import { isScope, Scope } from "./scope.ts";
+import { isScope, type Scope } from "./scope.ts";
 import { isSecret, Secret } from "./secret.ts";
 
 import type { Type } from "arktype";
@@ -77,7 +77,7 @@ export async function serializeScope(scope: Scope): Promise<SerializedScope> {
   async function serializeScope(scope: Scope): Promise<SerializedScope> {
     await Promise.all(
       Array.from(scope.resources.values()).map(async (resource) => {
-        if (resource[ResourceKind] === Scope.KIND) {
+        if (resource[ResourceKind] === "alchemy::Scope") {
           return;
         }
         map[resource[ResourceFQN]] = await serialize(scope, await resource, {
@@ -121,7 +121,7 @@ export async function serialize(
     if (!scope.password) {
       throw new Error(
         "Cannot serialize secret without password, did you forget to set password when initializing your alchemy app?\n" +
-          "See: https://alchemy.run/docs/concepts/secret.html#encryption-password",
+          "See: https://alchemy.run/concepts/secret/#encryption-password",
       );
     }
     return {
@@ -220,7 +220,7 @@ export async function deserialize(
       if (!scope.password) {
         throw new Error(
           "Cannot deserialize secret without password, did you forget to set password when initializing your alchemy app?\n" +
-            "See: https://alchemy.run/docs/concepts/secret.html#encryption-password",
+            "See: https://alchemy.run/concepts/secret/#encryption-password",
         );
       }
       if (typeof value["@secret"] === "object") {

package/src/sqlite/base-sqlite-state-store.ts

@@ -0,0 +1,199 @@
+import { and, eq, getTableColumns, inArray } from "drizzle-orm";
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+import path from "node:path";
+import type { Scope } from "../scope.ts";
+import type { State, StateStore } from "../state.ts";
+import * as schema from "./schema.ts";
+
+type Database = BaseSQLiteDatabase<any, any, typeof schema>;
+
+export interface SQLiteStateStoreOptions<T extends Database = Database> {
+  create: () => Promise<T>;
+}
+
+const { scope: _, ...columns } = getTableColumns(schema.resources);
+
+export class BaseSQLiteStateStore<T extends Database = Database>
+  implements StateStore
+{
+  private chain: string[];
+  private create: () => Promise<T>;
+  private dbPromise?: Promise<T>;
+
+  constructor(
+    private readonly scope: Scope,
+    options: SQLiteStateStoreOptions<T>,
+  ) {
+    this.chain = this.scope.chain;
+    this.create = options.create;
+  }
+
+  private async db() {
+    this.dbPromise ??= withExponentialBackoff("init", () => this.create());
+    return await this.dbPromise;
+  }
+
+  async init() {
+    await this.db();
+  }
+
+  async list() {
+    const ids = await this.run("list", (db) =>
+      db
+        .select({ id: schema.resources.id })
+        .from(schema.resources)
+        .where(eq(schema.resources.scope, this.chain)),
+    );
+    return ids.map((id) => id.id);
+  }
+
+  async count() {
+    return await this.run("count", (db) =>
+      db.$count(
+        db
+          .select({ id: schema.resources.id })
+          .from(schema.resources)
+          .where(eq(schema.resources.scope, this.chain)),
+      ),
+    );
+  }
+
+  async get(id: string) {
+    const [state] = await this.run("get", (db) =>
+      db
+        .select(columns)
+        .from(schema.resources)
+        .where(
+          and(
+            eq(schema.resources.id, id),
+            eq(schema.resources.scope, this.chain),
+          ),
+        ),
+    );
+    if (!state) {
+      return;
+    }
+    return await this.deserialize(state);
+  }
+
+  async getBatch(ids: string[]) {
+    const states = await this.run("getBatch", async (db) =>
+      db
+        .select(columns)
+        .from(schema.resources)
+        .where(
+          and(
+            inArray(schema.resources.id, ids),
+            eq(schema.resources.scope, this.chain),
+          ),
+        ),
+    );
+    return await this.deserializeMany(states);
+  }
+
+  async all() {
+    const states = await this.run("all", async (db) =>
+      db
+        .select(columns)
+        .from(schema.resources)
+        .where(eq(schema.resources.scope, this.chain)),
+    );
+    return await this.deserializeMany(states);
+  }
+
+  async set(_: string, state: State) {
+    const serialized = await this.serialize(state);
+    await this.run("set", (db) =>
+      db
+        .insert(schema.resources)
+        .values({
+          ...serialized,
+          scope: this.chain,
+        })
+        .onConflictDoUpdate({
+          target: [schema.resources.id, schema.resources.scope],
+          set: serialized,
+        }),
+    );
+  }
+
+  async delete(id: string) {
+    await this.run("delete", async (db) =>
+      db
+        .delete(schema.resources)
+        .where(
+          and(
+            eq(schema.resources.id, id),
+            eq(schema.resources.scope, this.chain),
+          ),
+        ),
+    );
+  }
+
+  private async run<U>(
+    label: string,
+    fn: (db: T) => Promise<U>,
+    attempt = 0,
+  ): Promise<U> {
+    const db = await this.db();
+    return await withExponentialBackoff(label, () => fn(db), attempt);
+  }
+
+  private async deserialize(
+    state: Omit<schema.Resource, "scope">,
+  ): Promise<State> {
+    const { deserialize } = await import("../serde.ts"); // dynamic import to avoid circular dependency
+    return await deserialize(this.scope, {
+      ...state,
+      oldProps: state.oldProps ?? undefined,
+    });
+  }
+
+  private async serialize(state: State) {
+    const { serialize } = await import("../serde.ts");
+    return await serialize(this.scope, state);
+  }
+
+  private async deserializeMany(states: Omit<schema.Resource, "scope">[]) {
+    const deserialized = await Promise.all(
+      states.map((state) => this.deserialize(state)),
+    );
+    const map: Record<string, State> = {};
+    for (const state of deserialized) {
+      map[state.id] = state;
+    }
+    return map;
+  }
+}
+
+const withExponentialBackoff = async <T>(
+  label: string,
+  fn: () => Promise<T>,
+  attempt = 0,
+): Promise<T> => {
+  try {
+    const result = await fn();
+    return result;
+  } catch (cause) {
+    if (attempt < 10) {
+      await delay(attempt);
+      return withExponentialBackoff(label, fn, attempt + 1);
+    }
+    throw new Error(
+      `[SQLiteStateStore] Failed to run "${label}" after 10 attempts`,
+      {
+        cause,
+      },
+    );
+  }
+};
+
+const delay = (attempt: number, initialDelay = 100, jitterFactor = 0.2) => {
+  const baseDelay = initialDelay * 2 ** attempt;
+  const jitter = Math.floor(Math.random() * baseDelay * jitterFactor);
+  return new Promise((resolve) => setTimeout(resolve, baseDelay + jitter));
+};
+
+export const resolveMigrationsPath = () => {
+  return path.join(import.meta.dirname, "..", "..", "drizzle");
+};

package/src/sqlite/index.ts

@@ -0,0 +1 @@
+export * from "./sqlite-state-store.ts";

package/src/sqlite/schema.ts

@@ -0,0 +1,37 @@
+import {
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+import type {
+  Resource as AlchemyResource,
+  ResourceProps,
+} from "../resource.ts";
+
+export const resources = sqliteTable(
+  "resources",
+  {
+    id: text("id").notNull(),
+    scope: text("scope", { mode: "json" }).$type<string[]>().notNull(),
+    status: text("status", {
+      enum: [
+        "creating",
+        "created",
+        "updating",
+        "updated",
+        "deleting",
+        "deleted",
+      ],
+    }).notNull(),
+    kind: text("kind").notNull(),
+    fqn: text("fqn").notNull(),
+    seq: integer("seq").notNull(),
+    data: text("data", { mode: "json" }).notNull().$type<Record<string, any>>(),
+    props: text("props", { mode: "json" }).$type<ResourceProps>(),
+    oldProps: text("oldProps", { mode: "json" }).$type<ResourceProps>(),
+    output: text("output", { mode: "json" }).notNull().$type<AlchemyResource>(),
+  },
+  (t) => [primaryKey({ columns: [t.scope, t.id] })],
+);
+export type Resource = typeof resources.$inferSelect;

package/src/sqlite/sqlite-state-store.ts

@@ -0,0 +1,174 @@
+import type { Config as LibSQLConfig } from "@libsql/client";
+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 * as schema from "./schema.ts";
+
+interface BunSQLiteStateStoreOptions {
+  /**
+   * Use `bun:sqlite` to connect to the SQLite database.
+   * Requires Bun.
+   */
+  engine: "bun";
+  /**
+   * The filename to use for the SQLite database.
+   * @default process.env.ALCHEMY_STATE_FILE if set, otherwise ".alchemy/state.sqlite"
+   */
+  filename?: string;
+
+  // Options are copied from Bun instead of inherited because Bun's type is not exported,
+  // and the constructor type isn't an interface so inheritance doesn't work.
+
+  readonly?: boolean;
+  create?: boolean;
+  readwrite?: boolean;
+  safeIntegers?: boolean;
+  strict?: boolean;
+}
+
+interface LibSQLStateStoreOptions extends Omit<LibSQLConfig, "url"> {
+  /**
+   * Use the `@libsql/client` library to connect to the SQLite database.
+   * Supported on Node.js and Bun.
+   */
+  engine: "libsql";
+  /**
+   * The filename to use for the SQLite database.
+   * @default process.env.ALCHEMY_STATE_FILE if set, otherwise ".alchemy/state.sqlite"
+   * @note If the `url` option is specified, this option is ignored.
+   */
+  filename?: string;
+  /**
+   * The database URL. Overrides the `filename` option.
+   *
+   * The client supports `libsql:`, `http:`/`https:`, `ws:`/`wss:` and `file:` URL. For more infomation,
+   * please refer to the project README:
+   *
+   * https://github.com/libsql/libsql-client-ts#supported-urls
+   */
+  url?: string;
+}
+
+interface AutoSQLiteStateStoreOptions {
+  /**
+   * Automatically choose the best SQLite engine based on your environment.
+   * @default "auto" - Uses `bun:sqlite` if available, otherwise uses `@libsql/client`.
+   */
+  engine?: "auto";
+
+  /**
+   * The filename to use for the SQLite database.
+   * @default ".alchemy/state.sqlite"
+   */
+  filename?: string;
+}
+
+type SQLiteStateStoreOptions =
+  | BunSQLiteStateStoreOptions
+  | LibSQLStateStoreOptions
+  | AutoSQLiteStateStoreOptions;
+
+export class SQLiteStateStore extends BaseSQLiteStateStore {
+  constructor(scope: Scope, options?: SQLiteStateStoreOptions) {
+    super(scope, {
+      create: async () => createDatabase(options),
+    });
+  }
+}
+
+const createDatabase = memoize(
+  async (options: SQLiteStateStoreOptions | undefined) => {
+    switch (options?.engine) {
+      case "bun":
+        return await createBunSQLiteDatabase(options);
+      case "libsql":
+        return await createLibSQLDatabase(options);
+      default: {
+        return await createDefaultDatabase(options?.filename);
+      }
+    }
+  },
+);
+
+async function createDefaultDatabase(filename: string | undefined) {
+  if ("Bun" in globalThis) {
+    return createBunSQLiteDatabase({ engine: "bun", filename });
+  }
+  return createLibSQLDatabase({ engine: "libsql", filename });
+}
+
+async function createBunSQLiteDatabase(
+  options: BunSQLiteStateStoreOptions | undefined,
+) {
+  if (!("Bun" in globalThis)) {
+    throw new Error(
+      "[SQLiteStateStore] The `engine: 'bun'` option is only available in Bun. Please use `engine: 'libsql'` instead.",
+    );
+  }
+
+  const filename =
+    options?.filename ??
+    process.env.ALCHEMY_STATE_FILE ??
+    ".alchemy/state.sqlite";
+  ensureDirectory(filename);
+  const { Database } = await import("bun:sqlite");
+  const { drizzle } = await import("drizzle-orm/bun-sqlite").catch(() => {
+    throw new Error(
+      "[SQLiteStateStore] Missing `drizzle-orm` peer dependency. Please `bun install drizzle-orm`.",
+    );
+  });
+  const { migrate } = await import("drizzle-orm/bun-sqlite/migrator");
+  // Bun's constructor throws if we pass in an empty object or if extraneous
+  // options are passed in, so here's some ugly destructuring!
+  const { engine: _engine, filename: _filename, ...rest } = options ?? {};
+  const bunOptions = Object.keys(rest).length > 0 ? rest : undefined;
+  const client = new Database(filename, bunOptions);
+  client.exec("PRAGMA journal_mode = WAL;");
+  const db = drizzle(client, {
+    schema,
+  });
+  migrate(db, { migrationsFolder: resolveMigrationsPath() });
+  return db;
+}
+
+async function createLibSQLDatabase(
+  options: LibSQLStateStoreOptions | undefined,
+) {
+  const url =
+    options?.url ??
+    `file:${options?.filename ?? process.env.ALCHEMY_STATE_FILE ?? ".alchemy/state.sqlite"}`;
+  const filename = url.startsWith("file:") ? url.slice(5) : undefined;
+  if (filename) {
+    ensureDirectory(filename);
+  }
+  const { createClient } = await import("@libsql/client").catch(() => {
+    throw new Error(
+      "[SQLiteStateStore] Missing `@libsql/client` peer dependency. Please `npm install @libsql/client`.",
+    );
+  });
+  const { drizzle } = await import("drizzle-orm/libsql").catch(() => {
+    throw new Error(
+      "[SQLiteStateStore] Missing `drizzle-orm` peer dependency. Please `npm install drizzle-orm`.",
+    );
+  });
+  const { migrate } = await import("drizzle-orm/libsql/migrator");
+  const client = createClient({ url, ...options });
+  await client.execute("PRAGMA journal_mode = WAL;");
+  const db = drizzle(client, {
+    schema,
+  });
+  await migrate(db, { migrationsFolder: resolveMigrationsPath() });
+  return db;
+}
+
+const ensureDirectory = (filename: string) => {
+  const dir = path.dirname(filename);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+};

package/src/test/bun.ts

@@ -3,7 +3,6 @@
 import { afterAll, beforeAll, it } from "bun:test";
 import path from "node:path";
 import { alchemy } from "../alchemy.ts";
-import { DOStateStore } from "../cloudflare/index.ts";
 import { Scope } from "../scope.ts";
 import type { StateStoreType } from "../state.ts";
 import { NoopTelemetryClient } from "../util/telemetry/index.ts";
@@ -120,13 +119,6 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
   defaultOptions = defaultOptions ?? {
     quiet: true,
   };
-  if (
-    defaultOptions.stateStore === undefined &&
-    // process.env.CI &&
-    process.env.ALCHEMY_STATE_STORE === "cloudflare"
-  ) {
-    defaultOptions.stateStore = (scope) => new DOStateStore(scope);
-  }
 
   // Add skipIf functionality
   test.skipIf = it.skipIf.bind(it);

package/src/test/vitest.ts

@@ -1,8 +1,11 @@
 import path from "node:path";
 import { afterAll, beforeAll, it } from "vitest";
 import { alchemy } from "../alchemy.ts";
-import { DOStateStore } from "../cloudflare/index.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 { NoopTelemetryClient } from "../util/telemetry/client.ts";
 
@@ -123,13 +126,21 @@ export function test(
   if (!("quiet" in defaultOptions)) {
     defaultOptions.quiet = true;
   }
-
-  if (
-    defaultOptions.stateStore === undefined &&
-    process.env.ALCHEMY_STATE_STORE === "cloudflare"
-  ) {
-    defaultOptions.stateStore = (scope) => new DOStateStore(scope);
-  }
+  defaultOptions.stateStore ??= (scope) => {
+    const storeType = process.env.ALCHEMY_STATE_STORE;
+    switch (storeType) {
+      case "dofs":
+        return new DOStateStore(scope);
+      case "fs":
+        return new FileSystemStateStore(scope);
+      case "d1":
+        return new D1StateStore(scope);
+      default:
+        return new SQLiteStateStore(scope, {
+          filename: `.alchemy/${path.relative(process.cwd(), meta.filename)}.sqlite`,
+        });
+    }
+  };
 
   test.skipIf = (condition: boolean) => {
     if (condition) {

package/src/util/memoize.ts

@@ -1,10 +1,12 @@
+import { createHash } from "node:crypto";
+
 type AsyncReturnType<T> = T extends (...args: any[]) => Promise<infer R>
   ? R
   : T;
 
 export function memoize<F extends (...args: any[]) => Promise<any>>(
   fn: F,
-  keyFn: (...args: Parameters<F>) => string,
+  keyFn: (...args: Parameters<F>) => string = defaultKeyFn,
 ) {
   const cache = new Map<string, Promise<AsyncReturnType<F>>>();
   return async (...args: Parameters<F>): Promise<AsyncReturnType<F>> => {
@@ -21,3 +23,13 @@ export function memoize<F extends (...args: any[]) => Promise<any>>(
     return await promise;
   };
 }
+
+const defaultKeyFn = (...args: any[]) => {
+  const hash = createHash("sha256");
+  args.forEach((arg) => {
+    if (arg) {
+      hash.update(JSON.stringify(arg));
+    }
+  });
+  return hash.digest("hex");
+};

package/templates/astro/types/env.d.ts

@@ -1,5 +1,5 @@
 // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
-// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
+// @see https://alchemy.run/concepts/bindings/#type-safe-bindings
 
 import type { worker } from "../alchemy.run.ts";
 

package/templates/nuxt/types/env.d.ts

@@ -1,5 +1,5 @@
 // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
-// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
+// @see https://alchemy.run/concepts/bindings/#type-safe-bindings
 
 import type { worker } from "../alchemy.run.ts";
 

package/templates/react-router/types/env.d.ts

@@ -1,5 +1,5 @@
 // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
-// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
+// @see https://alchemy.run/concepts/bindings/#type-safe-bindings
 
 import type { worker } from "../alchemy.run.ts";
 

package/templates/rwsdk/types/env.d.ts

@@ -1,5 +1,5 @@
 // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
-// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
+// @see https://alchemy.run/concepts/bindings/#type-safe-bindings
 
 import type { worker } from "../alchemy.run.ts";
 

package/templates/sveltekit/types/env.d.ts

@@ -1,5 +1,5 @@
 // This file infers types for the cloudflare:workers environment from your Alchemy Worker.
-// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings
+// @see https://alchemy.run/concepts/bindings/#type-safe-bindings
 
 import type { worker } from "../alchemy.run.ts";