@samebase/alchemy-convex 0.4.1 → 0.6.0

package/src/store/convex/_generated/server.d.ts

@@ -0,0 +1,162 @@
+/* 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 {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} 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 declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const httpAction: HttpActionBuilder;
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+export declare const env: 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.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+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.
+ */
+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/store/convex/_generated/server.js

@@ -0,0 +1,101 @@
+/* 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 {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+
+/**
+ * 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 = 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 = 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 = 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 = 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 = 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 = 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 = httpActionGeneric;
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+export const env = process.env;

package/src/store/convex/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/store/convex/state.ts

@@ -0,0 +1,219 @@
+// The state functions of the alchemy-state project: one project for each
+// Convex team, pushed by Convex.state() from this directory. Every function
+// is internal: a public function of a root app answers anyone who knows the
+// deployment URL, with no key (measured). An internal function answers only
+// POST /api/function with a deploy key of the production deployment, the
+// call that `convex run` makes.
+//
+// A stage holds one row for each resource of its stack, so the reads of one
+// stage collect all rows. The function names are a wire contract: Samebase
+// reads `stacks` and `getOutput` by name, and an older client calls an older
+// set of names. Add functions; never rename or remove one.
+import { v } from "convex/values";
+import type { QueryCtx } from "./_generated/server.js";
+import { internalMutation, internalQuery } from "./_generated/server.js";
+import { STORE_VERSION } from "./version.ts";
+
+/** The wire version of this store, compared with the client's STORE_VERSION. */
+export const version = internalQuery({
+  args: {},
+  returns: v.number(),
+  handler: async () => STORE_VERSION,
+});
+
+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();
+
+/** The sorted union of two lists of names. */
+const union = (a: readonly string[], b: readonly string[]) => [...new Set([...a, ...b])].sort();
+
+/**
+ * The distinct names of one table in index order, with one index read for
+ * each name: `first(after)` is the first row whose name is above `after`.
+ */
+const distinct = async (first: (after: string | undefined) => Promise<string | null>) => {
+  const names: string[] = [];
+  for (;;) {
+    const next = await first(names.at(-1));
+    if (next === null) return names;
+    names.push(next);
+  }
+};
+
+/** Stacks with at least one resource or one output, sorted. */
+export const stacks = internalQuery({
+  args: {},
+  returns: v.array(v.string()),
+  handler: async (ctx) =>
+    union(
+      await distinct(
+        async (after) =>
+          (
+            await ctx.db
+              .query("resources")
+              .withIndex("by_fqn", (q) => (after === undefined ? q : q.gt("stack", after)))
+              .first()
+          )?.stack ?? null,
+      ),
+      await distinct(
+        async (after) =>
+          (
+            await ctx.db
+              .query("outputs")
+              .withIndex("by_stage", (q) => (after === undefined ? q : q.gt("stack", after)))
+              .first()
+          )?.stack ?? null,
+      ),
+    ),
+});
+
+/** Stages of a stack with at least one resource or one output, sorted. */
+export const stages = internalQuery({
+  args: { stack: v.string() },
+  returns: v.array(v.string()),
+  handler: async (ctx, args) =>
+    union(
+      await distinct(
+        async (after) =>
+          (
+            await ctx.db
+              .query("resources")
+              .withIndex("by_fqn", (q) =>
+                after === undefined
+                  ? q.eq("stack", args.stack)
+                  : q.eq("stack", args.stack).gt("stage", after),
+              )
+              .first()
+          )?.stage ?? null,
+      ),
+      await distinct(
+        async (after) =>
+          (
+            await ctx.db
+              .query("outputs")
+              .withIndex("by_stage", (q) =>
+                after === undefined
+                  ? q.eq("stack", args.stack)
+                  : q.eq("stack", args.stack).gt("stage", after),
+              )
+              .first()
+          )?.stage ?? null,
+      ),
+    ),
+});
+
+export const list = internalQuery({
+  args: stage,
+  returns: v.array(v.string()),
+  handler: async (ctx, args) => (await rowsOf(ctx, args)).map((row) => row.fqn),
+});
+
+export const get = internalQuery({
+  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 = internalQuery({
+  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 = internalMutation({
+  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 = internalMutation({
+  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 = internalMutation({
+  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 = internalQuery({
+  args: stage,
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx, args) => (await outputOf(ctx, args))?.value ?? null,
+});
+
+export const setOutput = internalMutation({
+  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/store/convex/version.ts

@@ -0,0 +1,6 @@
+// The wire version of the store: the `state:version` query answers it, and
+// Convex.state() pushes this directory when the store of the team answers an
+// older one or has no `version` yet. Raise it when a function changes in a way
+// that an older client cannot use. Never rename or remove a function: an
+// older client, and Samebase, call the store by these names.
+export const STORE_VERSION = 1;

package/src/store/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "alchemy-state",
+  "private": true,
+  "type": "module",
+  "peerDependencies": {
+    "convex": "^1.46.0"
+  }
+}