@samebase/alchemy-convex 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",
@@ -51,24 +51,25 @@
     "@convex-dev/platform": "0.1.11"
   },
   "devDependencies": {
+    "@alchemy.run/cloudflare": "2.0.0-beta.84",
     "@arethetypeswrong/core": "0.18.5",
-    "@effect/platform-node": "4.0.4",
-    "@effect/vitest": "4.0.4",
+    "@effect/platform-node": "4.0.5",
+    "@effect/vitest": "4.0.5",
     "@types/node": "24.19.2",
-    "alchemy": "2.0.0-beta.83",
+    "alchemy": "2.0.0-beta.84",
     "convex": "1.48.0",
     "convex-test": "0.0.60",
-    "effect": "4.0.4",
+    "effect": "4.0.5",
     "publint": "0.3.25",
     "typescript": "6.0.3",
     "vite-plus": "1.1.0",
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@effect/platform-node": "^4.0.0",
-    "alchemy": "2.0.0-beta.83",
+    "@effect/platform-node": "^4.0.5",
+    "alchemy": "2.0.0-beta.84",
     "convex": "^1.48.0",
-    "effect": "^4.0.0"
+    "effect": "^4.0.5"
   },
   "engines": {
     "node": ">=22"

package/src/Component.ts

@@ -0,0 +1,54 @@
+import { toPath } from "alchemy/FQN";
+import type { NamespaceNode } from "alchemy/Namespace";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { Deployment } from "./Deployment.ts";
+
+/** A component's resources occupy this namespace in the deployment's Alchemy stack and stage. */
+export interface ComponentBinding {
+  readonly type: "component";
+  readonly path: string;
+  readonly namespace: readonly string[];
+}
+
+/**
+ * Associate a native namespace with an installed component. `component` is the
+ * installed name from the app's `convex.config.ts`; a nested install joins the
+ * names with slashes, such as `"workspace/mail"`. An undefined namespace
+ * associates the stack root. This records display metadata; it does not install
+ * the component, set its environment, or change removal policies.
+ */
+export const bindComponent = (options: {
+  deployment: Deployment;
+  component: string;
+  namespace: NamespaceNode | undefined;
+}) =>
+  Effect.gen(function* () {
+    if (options.component === "") {
+      return yield* Effect.die(new Error("The component name is empty."));
+    }
+    const namespace = toPath(options.namespace);
+    const sid = `convex.component:${JSON.stringify(namespace)}`;
+    const stack = yield* Stack;
+    const previous = stack.bindings[options.deployment.FQN]?.find((binding) => binding.sid === sid);
+    // Alchemy keeps the last binding with a given sid. Reject conflicting owners before that happens.
+    if (previous !== undefined) {
+      const existing = Schema.decodeUnknownSync(Schema.Struct({ path: Schema.String }))(
+        previous.data,
+      );
+      if (existing.path !== options.component) {
+        return yield* Effect.die(
+          new Error(
+            `Alchemy namespace ${JSON.stringify(namespace)} is already bound to ${existing.path}.`,
+          ),
+        );
+      }
+      return;
+    }
+    yield* options.deployment.bind(sid, {
+      type: "component",
+      path: options.component,
+      namespace,
+    });
+  });

package/src/Deployment.ts

@@ -54,7 +54,7 @@
 import { posix, win32 } from "node:path";
 import { Resource } from "alchemy";
 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
-import { isResolved } from "alchemy/Diff";
+import { diffBindings, isResolved } from "alchemy/Diff";
 import type { InputProps } from "alchemy/Input";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
@@ -63,6 +63,7 @@ import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 import { shouldAdopt } from "./Adoption.ts";
 import { Credentials } from "./Credentials.ts";
+import type { ComponentBinding } from "./Component.ts";
 import {
   absentAsUndefined,
   type ConvexApiError,
@@ -145,7 +146,7 @@ export type Deployment = Resource<
   "Convex.Deployment",
   DeploymentProps,
   DeploymentAttributes,
-  never,
+  ComponentBinding,
   Providers
 >;
 /** The resource class. Stacks call {@link Deployment}, which writes `rootDir` into the props. */
@@ -597,9 +598,10 @@ export const DeploymentProvider = () =>
         // the refused props. Only `rootDir` compares with `olds`, because it
         // is in the props only. A refused update leaves the row `updating`,
         // and the next plan updates it again anyway.
-        diff: Effect.fn(function* ({ news, olds, output }) {
+        diff: Effect.fn(function* ({ news, olds, output, oldBindings, newBindings }) {
           if (!isResolved(news) || output === undefined) return undefined;
           yield* checkIdentity(output, news);
+          if (!isResolved(newBindings)) return undefined;
           // State from 0.7 has no rootDir; the constructor always writes it.
           const rootDir = news.rootDir ?? ".";
           // Also here, so that a wrong rootDir stops the plan before Apply
@@ -617,9 +619,21 @@ export const DeploymentProvider = () =>
           const current = yield* live(access, output);
           if (current?.name !== output.name) return { action: "update" } as const;
           const hash = yield* wantedHash(news, rootDir, output.name);
-          return hash === output.hash
-            ? ({ action: "noop" } as const)
-            : ({ action: "update" } as const);
+          if (hash !== output.hash) return { action: "update" } as const;
+          if (diffBindings(oldBindings, newBindings).every((binding) => binding.action === "noop"))
+            return { action: "noop" } as const;
+          // Binding metadata does not change deployment outputs. Keep unchanged
+          // values available to consumers so the plan does not update them too.
+          return {
+            action: "update" as const,
+            stables: [
+              "hash",
+              "envNames",
+              ...(
+                ["projectId", "type", "previewName", "name", "reference", "url", "siteUrl"] as const
+              ).filter((key) => current[key] === output[key]),
+            ],
+          };
         }),
 
         read: Effect.fn(function* ({ olds, output }) {

package/src/index.ts

@@ -1,4 +1,5 @@
 // @samebase/alchemy-convex: the Convex plane for Alchemy v2.
+export { bindComponent, type ComponentBinding } from "./Component.ts";
 export {
   ACCESS_TOKEN_ENV,
   Credentials,