@xixixao/convex-migrations 0.3.1

package/src/client/log.ts

@@ -0,0 +1,76 @@
+import type { MigrationStatus } from "../shared.js";
+
+export function logStatusAndInstructions(
+  name: string,
+  status: MigrationStatus,
+  args: {
+    fn?: string;
+    cursor?: string | null;
+    batchSize?: number;
+    dryRun?: boolean;
+  },
+) {
+  const output: Record<string, unknown> = {};
+  if (status.isDone) {
+    if (status.latestEnd! < Date.now()) {
+      output["Status"] = "Migration already done.";
+    } else if (status.latestStart === status.latestEnd) {
+      output["Status"] = "Migration was started and finished in one batch.";
+    } else {
+      output["Status"] = "Migration completed with this batch.";
+    }
+  } else {
+    if (status.state === "failed") {
+      output["Status"] = `Migration failed: ${status.error}`;
+    } else if (status.state === "canceled") {
+      output["Status"] = "Migration canceled.";
+    } else if (status.latestStart >= Date.now()) {
+      output["Status"] = "Migration started.";
+    } else {
+      output["Status"] = "Migration running.";
+    }
+  }
+  if (args.dryRun) {
+    output["DryRun"] = "No changes were committed.";
+    output["Status"] = "DRY RUN: " + output["Status"];
+  }
+  output["Name"] = name;
+  output["lastStarted"] = new Date(status.latestStart).toISOString();
+  if (status.latestEnd) {
+    output["lastFinished"] = new Date(status.latestEnd).toISOString();
+  }
+  output["processed"] = status.processed;
+  if (status.next?.length) {
+    if (status.isDone) {
+      output["nowUp"] = status.next;
+    } else {
+      output["nextUp"] = status.next;
+    }
+  }
+  const nextArgs = (status.next || []).map((n) => `"${n}"`).join(", ");
+  const run = `npx convex run --component migrations`;
+  if (!args.dryRun) {
+    if (status.state === "inProgress") {
+      output["toCancel"] = {
+        cmd: `${run} lib:cancel`,
+        args: `{"name": "${name}"}`,
+        prod: `--prod`,
+      };
+      output["toMonitorStatus"] = {
+        cmd: `${run} --watch lib:getStatus`,
+        args: `{"names": ["${name}"${status.next?.length ? ", " + nextArgs : ""}]}`,
+        prod: `--prod`,
+      };
+    } else {
+      output["toStartOver"] = JSON.stringify({ ...args, cursor: null });
+      if (status.next?.length) {
+        output["toMonitorStatus"] = {
+          cmd: `${run} --watch lib:getStatus`,
+          args: `{"names": [${nextArgs}]}`,
+          prod: `--prod`,
+        };
+      }
+    }
+  }
+  return output;
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,116 @@
+/* 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> =
+  {
+    lib: {
+      cancel: FunctionReference<
+        "mutation",
+        "internal",
+        { name: string },
+        {
+          batchSize?: number;
+          cursor?: string | null;
+          error?: string;
+          isDone: boolean;
+          latestEnd?: number;
+          latestStart: number;
+          name: string;
+          next?: Array<string>;
+          processed: number;
+          state: "inProgress" | "success" | "failed" | "canceled" | "unknown";
+        },
+        Name
+      >;
+      cancelAll: FunctionReference<
+        "mutation",
+        "internal",
+        { sinceTs?: number },
+        Array<{
+          batchSize?: number;
+          cursor?: string | null;
+          error?: string;
+          isDone: boolean;
+          latestEnd?: number;
+          latestStart: number;
+          name: string;
+          next?: Array<string>;
+          processed: number;
+          state: "inProgress" | "success" | "failed" | "canceled" | "unknown";
+        }>,
+        Name
+      >;
+      clearAll: FunctionReference<
+        "mutation",
+        "internal",
+        { before?: number },
+        null,
+        Name
+      >;
+      getStatus: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number; names?: Array<string> },
+        Array<{
+          batchSize?: number;
+          cursor?: string | null;
+          error?: string;
+          isDone: boolean;
+          latestEnd?: number;
+          latestStart: number;
+          name: string;
+          next?: Array<string>;
+          processed: number;
+          state: "inProgress" | "success" | "failed" | "canceled" | "unknown";
+        }>,
+        Name
+      >;
+      migrate: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          args?: any;
+          batchSize?: number;
+          cursor?: string | null;
+          dryRun: boolean;
+          fnHandle: string;
+          name: string;
+          next?: Array<{ fnHandle: string; name: string }>;
+          oneBatchOnly?: boolean;
+        },
+        {
+          batchSize?: number;
+          cursor?: string | null;
+          error?: string;
+          isDone: boolean;
+          latestEnd?: number;
+          latestStart: number;
+          name: string;
+          next?: Array<string>;
+          processed: number;
+          state: "inProgress" | "success" | "failed" | "canceled" | "unknown";
+        },
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,161 @@
+/* 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";
+
+/**
+ * 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;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * 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,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("migrations");

package/src/component/lib.test.ts

@@ -0,0 +1,110 @@
+import { describe, test, expect } from "vitest";
+import {
+  type ApiFromModules,
+  anyApi,
+  createFunctionHandle,
+} from "convex/server";
+import { convexTest } from "convex-test";
+import { modules } from "./setup.test.js";
+import { api } from "./_generated/api.js";
+import type { MigrationArgs, MigrationResult } from "../client/index.js";
+import { mutation } from "./_generated/server.js";
+import schema from "./schema.js";
+
+export const doneMigration = mutation({
+  handler: async (_, _args: MigrationArgs): Promise<MigrationResult> => {
+    return {
+      isDone: true,
+      continueCursor: "foo",
+      processed: 1,
+    };
+  },
+});
+
+const testApi: ApiFromModules<{
+  fns: { doneMigration: typeof doneMigration };
+}>["fns"] = anyApi["lib.test"] as any;
+
+describe("migrate", () => {
+  test("runs a simple migration in one go", async () => {
+    const t = convexTest(schema, modules);
+    const fnHandle = await createFunctionHandle(testApi.doneMigration);
+    const result = await t.mutation(api.lib.migrate, {
+      name: "testMigration",
+      fnHandle: fnHandle,
+      dryRun: false,
+    });
+    expect(result.isDone).toBe(true);
+    expect(result.cursor).toBe("foo");
+    expect(result.processed).toBe(1);
+    expect(result.error).toBeUndefined();
+    expect(result.batchSize).toBeUndefined();
+    expect(result.next).toBeUndefined();
+    expect(result.latestEnd).toBeTypeOf("number");
+    expect(result.state).toBe("success");
+  });
+
+  test("throws error for batchSize <= 0", async () => {
+    const args = {
+      name: "testMigration",
+      fnHandle: "function://dummy",
+      cursor: null,
+      batchSize: 0,
+      next: [],
+      dryRun: false,
+    };
+    const t = convexTest(schema, modules);
+    // Assumes testApi has shape matching api.lib – adjust per actual ConvexTest usage
+    await expect(t.mutation(api.lib.migrate, args)).rejects.toThrow(
+      "Batch size must be greater than 0",
+    );
+  });
+
+  test("throws error for invalid fnHandle", async () => {
+    const args = {
+      name: "testMigration",
+      fnHandle: "invalid_handle",
+      cursor: null,
+      batchSize: 10,
+      next: [],
+      dryRun: false,
+    };
+    const t = convexTest(schema, modules);
+    await expect(t.mutation(api.lib.migrate, args)).rejects.toThrow(
+      "Invalid fnHandle",
+    );
+  });
+});
+
+describe("cancel", () => {
+  test("throws error if migration not found", async () => {
+    // For cancel, ConvexTest-like patterns would be similar – this code demonstrates minimal direct call
+    const t = convexTest(schema, modules);
+    await expect(
+      t.mutation(api.lib.cancel, { name: "nonexistent" }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("It doesn't attempt a migration if it's already done", () => {
+  test("runs a simple migration in one go", async () => {
+    const t = convexTest(schema, modules);
+    const fnHandle = "function://invalid";
+    await t.run((ctx) =>
+      ctx.db.insert("migrations", {
+        name: "testMigration",
+        latestStart: Date.now(),
+        isDone: true,
+        cursor: "foo",
+        processed: 1,
+      }),
+    );
+    // It'd throw if it tried to run the migration.
+    const result = await t.mutation(api.lib.migrate, {
+      name: "testMigration",
+      fnHandle: fnHandle,
+      dryRun: false,
+    });
+    expect(result.isDone).toBe(true);
+  });
+});