@samebase/alchemy-convex 0.4.0 → 0.5.0

package/src/component/_generated/server.ts

@@ -0,0 +1,169 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+type Env = {
+  readonly CONVEX_CLOUD_URL: string;
+  readonly CONVEX_SITE_URL: string;
+};
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+export const env: Env = (globalThis as unknown as { process: { env: Env } })
+  .process.env;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,5 @@
+// The Alchemy state store of a Convex app. Mount it with its default name:
+// `Convex.state()` calls it at the component path "alchemyState".
+import { defineComponent } from "convex/server";
+
+export default defineComponent("alchemyState");

package/src/component/schema.ts

@@ -0,0 +1,19 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+// `value` is the JSON text of Alchemy's encodeState(...): the same text that
+// Alchemy's local state writes to a file. A Convex object would reject keys
+// that Alchemy state can hold, such as keys that start with "$".
+export default defineSchema({
+  resources: defineTable({
+    stack: v.string(),
+    stage: v.string(),
+    fqn: v.string(),
+    value: v.string(),
+  }).index("by_fqn", ["stack", "stage", "fqn"]),
+  outputs: defineTable({
+    stack: v.string(),
+    stage: v.string(),
+    value: v.string(),
+  }).index("by_stage", ["stack", "stage"]),
+});

package/src/component/state.ts

@@ -0,0 +1,169 @@
+// The state functions. A component function is not part of the public API of
+// the app: only POST /api/function with a deploy key reaches it, and that key
+// needs `deployment:data:view` for a query and `deployment:data:write` for a
+// mutation (measured).
+//
+// A stage holds one row for each resource of its stack, so the reads of one
+// stage collect all rows.
+import { v } from "convex/values";
+import type { QueryCtx } from "./_generated/server.js";
+import { mutation, query } from "./_generated/server.js";
+
+const stage = { stack: v.string(), stage: v.string() };
+const resource = { ...stage, fqn: v.string() };
+
+const rowOf = (ctx: QueryCtx, args: { stack: string; stage: string; fqn: string }) =>
+  ctx.db
+    .query("resources")
+    .withIndex("by_fqn", (q) =>
+      q.eq("stack", args.stack).eq("stage", args.stage).eq("fqn", args.fqn),
+    )
+    .unique();
+
+const rowsOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
+  ctx.db
+    .query("resources")
+    .withIndex("by_fqn", (q) => q.eq("stack", args.stack).eq("stage", args.stage))
+    .collect();
+
+const outputOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
+  ctx.db
+    .query("outputs")
+    .withIndex("by_stage", (q) => q.eq("stack", args.stack).eq("stage", args.stage))
+    .unique();
+
+/** Stacks with at least one resource, in index order: one index read for each stack. */
+export const stacks = query({
+  args: {},
+  returns: v.array(v.string()),
+  handler: async (ctx) => {
+    const names: string[] = [];
+    for (;;) {
+      const last = names.at(-1);
+      const next = await ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) => (last === undefined ? q : q.gt("stack", last)))
+        .first();
+      if (next === null) return names;
+      names.push(next.stack);
+    }
+  },
+});
+
+/** Stages of a stack with at least one resource, in index order. */
+export const stages = query({
+  args: { stack: v.string() },
+  returns: v.array(v.string()),
+  handler: async (ctx, args) => {
+    const names: string[] = [];
+    for (;;) {
+      const last = names.at(-1);
+      const next = await ctx.db
+        .query("resources")
+        .withIndex("by_fqn", (q) =>
+          last === undefined
+            ? q.eq("stack", args.stack)
+            : q.eq("stack", args.stack).gt("stage", last),
+        )
+        .first();
+      if (next === null) return names;
+      names.push(next.stage);
+    }
+  },
+});
+
+export const list = query({
+  args: stage,
+  returns: v.array(v.string()),
+  handler: async (ctx, args) => (await rowsOf(ctx, args)).map((row) => row.fqn),
+});
+
+export const get = query({
+  args: resource,
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx, args) => (await rowOf(ctx, args))?.value ?? null,
+});
+
+/** Resources whose state has `status: "replaced"`. */
+export const replaced = query({
+  args: stage,
+  returns: v.array(v.string()),
+  handler: async (ctx, args) =>
+    (await rowsOf(ctx, args))
+      .map((row) => row.value)
+      .filter((value) => {
+        const parsed: unknown = JSON.parse(value);
+        return (
+          typeof parsed === "object" &&
+          parsed !== null &&
+          "status" in parsed &&
+          parsed.status === "replaced"
+        );
+      }),
+});
+
+export const set = mutation({
+  args: { ...resource, value: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await rowOf(ctx, args);
+    if (row === null) await ctx.db.insert("resources", args);
+    else await ctx.db.patch("resources", row._id, { value: args.value });
+    return null;
+  },
+});
+
+export const remove = mutation({
+  args: resource,
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await rowOf(ctx, args);
+    if (row !== null) await ctx.db.delete("resources", row._id);
+    return null;
+  },
+});
+
+/** Deletes the resources and outputs of one stage, or of every stage of the stack. */
+export const removeStack = mutation({
+  args: { stack: v.string(), stage: v.optional(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const { stack } = args;
+    const resources = await ctx.db
+      .query("resources")
+      .withIndex("by_fqn", (q) =>
+        args.stage === undefined
+          ? q.eq("stack", stack)
+          : q.eq("stack", stack).eq("stage", args.stage),
+      )
+      .collect();
+    const outputs = await ctx.db
+      .query("outputs")
+      .withIndex("by_stage", (q) =>
+        args.stage === undefined
+          ? q.eq("stack", stack)
+          : q.eq("stack", stack).eq("stage", args.stage),
+      )
+      .collect();
+    for (const row of resources) await ctx.db.delete("resources", row._id);
+    for (const row of outputs) await ctx.db.delete("outputs", row._id);
+    return null;
+  },
+});
+
+export const getOutput = query({
+  args: stage,
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx, args) => (await outputOf(ctx, args))?.value ?? null,
+});
+
+export const setOutput = mutation({
+  args: { ...stage, value: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await outputOf(ctx, args);
+    if (row === null) await ctx.db.insert("outputs", args);
+    else await ctx.db.patch("outputs", row._id, { value: args.value });
+    return null;
+  },
+});

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   ProjectTeamChange,
 } from "./Project.ts";
 export { Providers, providers } from "./Providers.ts";
+export { STATE_DEPLOY_KEY_ENV, state } from "./State.ts";
 export {
   CodePushFailed,
   ConvexAppNotFound,