@samebase/alchemy-convex 0.5.0 → 0.6.0

package/src/{component/_generated/server.ts → store/convex/_generated/server.d.ts}

@@ -8,7 +8,7 @@
  * @module
  */
 
-import type {
+import {
   ActionBuilder,
   HttpActionBuilder,
   MutationBuilder,
@@ -19,15 +19,6 @@ import type {
   GenericDatabaseReader,
   GenericDatabaseWriter,
 } from "convex/server";
-import {
-  actionGeneric,
-  httpActionGeneric,
-  queryGeneric,
-  mutationGeneric,
-  internalActionGeneric,
-  internalMutationGeneric,
-  internalQueryGeneric,
-} from "convex/server";
 import type { DataModel } from "./dataModel.js";
 
 /**
@@ -49,7 +40,7 @@ type Env = {
  * @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;
+export declare const query: QueryBuilder<DataModel, "public">;
 
 /**
  * Define a query that is only accessible from other Convex functions (but not from the client).
@@ -59,8 +50,7 @@ export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
  * @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;
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
 
 /**
  * Define a mutation in this Convex app's public API.
@@ -70,7 +60,7 @@ export const internalQuery: QueryBuilder<DataModel, "internal"> =
  * @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;
+export declare const mutation: MutationBuilder<DataModel, "public">;
 
 /**
  * Define a mutation that is only accessible from other Convex functions (but not from the client).
@@ -80,8 +70,7 @@ export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
  * @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;
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
 
 /**
  * Define an action in this Convex app's public API.
@@ -94,7 +83,7 @@ export const internalMutation: MutationBuilder<DataModel, "internal"> =
  * @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;
+export declare const action: ActionBuilder<DataModel, "public">;
 
 /**
  * Define an action that is only accessible from other Convex functions (but not from the client).
@@ -102,8 +91,7 @@ export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
  * @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;
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
 
 /**
  * Define an HTTP action.
@@ -116,9 +104,15 @@ export const internalAction: ActionBuilder<DataModel, "internal"> =
  * 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;
+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.
@@ -126,7 +120,8 @@ export const env: Env = (globalThis as unknown as { process: { env: Env } })
  * 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.
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
  */
 export type QueryCtx = GenericQueryCtx<DataModel>;
 
@@ -135,8 +130,6 @@ export type QueryCtx = GenericQueryCtx<DataModel>;
  *
  * 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>;
 

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/{component → store/convex}/state.ts

@@ -1,13 +1,25 @@
-// 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).
+// 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.
+// 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 { mutation, query } 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() };
@@ -32,60 +44,98 @@ const outputOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
     .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({
+/** 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) => {
-    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);
-    }
-  },
+  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, in index order. */
-export const stages = query({
+/** 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) => {
-    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);
-    }
-  },
+  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 = query({
+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 = query({
+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 = query({
+export const replaced = internalQuery({
   args: stage,
   returns: v.array(v.string()),
   handler: async (ctx, args) =>
@@ -102,7 +152,7 @@ export const replaced = query({
       }),
 });
 
-export const set = mutation({
+export const set = internalMutation({
   args: { ...resource, value: v.string() },
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -113,7 +163,7 @@ export const set = mutation({
   },
 });
 
-export const remove = mutation({
+export const remove = internalMutation({
   args: resource,
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -124,7 +174,7 @@ export const remove = mutation({
 });
 
 /** Deletes the resources and outputs of one stage, or of every stage of the stack. */
-export const removeStack = mutation({
+export const removeStack = internalMutation({
   args: { stack: v.string(), stage: v.optional(v.string()) },
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -151,13 +201,13 @@ export const removeStack = mutation({
   },
 });
 
-export const getOutput = query({
+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 = mutation({
+export const setOutput = internalMutation({
   args: { ...stage, value: v.string() },
   returns: v.null(),
   handler: async (ctx, args) => {

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"
+  }
+}

package/src/component/_generated/component.ts

@@ -1,92 +0,0 @@
-/* eslint-disable */
-/**
- * Generated `ComponentApi` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type { FunctionReference } from "convex/server";
-
-/**
- * A utility for referencing a Convex component's exposed API.
- *
- * Useful when expecting a parameter like `components.myComponent`.
- * Usage:
- * ```ts
- * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
- *   return ctx.runQuery(component.someFile.someQuery, { ...args });
- * }
- * ```
- */
-export type ComponentApi<Name extends string | undefined = string | undefined> =
-  {
-    state: {
-      get: FunctionReference<
-        "query",
-        "internal",
-        { fqn: string; stack: string; stage: string },
-        string | null,
-        Name
-      >;
-      getOutput: FunctionReference<
-        "query",
-        "internal",
-        { stack: string; stage: string },
-        string | null,
-        Name
-      >;
-      list: FunctionReference<
-        "query",
-        "internal",
-        { stack: string; stage: string },
-        Array<string>,
-        Name
-      >;
-      remove: FunctionReference<
-        "mutation",
-        "internal",
-        { fqn: string; stack: string; stage: string },
-        null,
-        Name
-      >;
-      removeStack: FunctionReference<
-        "mutation",
-        "internal",
-        { stack: string; stage?: string },
-        null,
-        Name
-      >;
-      replaced: FunctionReference<
-        "query",
-        "internal",
-        { stack: string; stage: string },
-        Array<string>,
-        Name
-      >;
-      set: FunctionReference<
-        "mutation",
-        "internal",
-        { fqn: string; stack: string; stage: string; value: string },
-        null,
-        Name
-      >;
-      setOutput: FunctionReference<
-        "mutation",
-        "internal",
-        { stack: string; stage: string; value: string },
-        null,
-        Name
-      >;
-      stacks: FunctionReference<"query", "internal", {}, Array<string>, Name>;
-      stages: FunctionReference<
-        "query",
-        "internal",
-        { stack: string },
-        Array<string>,
-        Name
-      >;
-    };
-  };

package/src/component/convex.config.ts

@@ -1,5 +0,0 @@
-// 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");