alchemy 2.0.0-beta.60 → 2.0.0-beta.62

package/src/Ref.ts

@@ -20,6 +20,14 @@ export interface RefMetadata<R extends ResourceLike> {
   id: R["LogicalId"];
   stack?: string;
   stage?: string;
+  /**
+   * The resource type of the ref's target (e.g.
+   * `"Cloudflare.KV.Namespace"`). Known statically — `MyResource.ref`
+   * carries its own type — so duck-typing classifiers (Worker env
+   * bindings, capability helpers) that read `.Type` can identify a ref
+   * exactly like a locally-declared resource.
+   */
+  type?: string;
 }
 
 export const ref = <R extends ResourceLike>(
@@ -31,6 +39,7 @@ export const ref = <R extends ResourceLike>(
     stack?: string;
     stage?: string;
   } = {},
+  type?: string,
 ): Ref<R> => {
   const ref = new Proxy(
     {},
@@ -41,6 +50,7 @@ export const ref = <R extends ResourceLike>(
             stack,
             stage,
             id,
+            type,
           } satisfies RefMetadata<R>;
         }
         return (Output.of(ref) as any)[prop];

package/src/Resource.ts

@@ -45,6 +45,13 @@ export interface ResourceClassLike<R extends ResourceLike> {
   Props: R["Props"];
   Self: Self<R>;
   Provider: Provider<R>;
+  /**
+   * Legacy type names this resource was previously registered under
+   * (see {@link ResourceOptions.aliases}). Copied onto the
+   * `ProviderService` by `Provider.succeed`/`Provider.effect` so provider
+   * lookup can resolve state persisted under a pre-rename type.
+   */
+  Aliases?: readonly string[];
 }
 
 export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
@@ -54,6 +61,7 @@ export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    Aliases: readonly string[] | undefined;
     ref(
       id: string,
       options?: { stage?: string; stack?: string },
@@ -70,6 +78,7 @@ export type ResourceClassWithMethods<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    Aliases: readonly string[] | undefined;
     ref(
       id: string,
       options?: { stage?: string; stack?: string },
@@ -133,6 +142,28 @@ export const isResource = (value: any): value is ResourceLike => {
   return typeof value === "object" && value !== null && "Type" in value;
 };
 
+/**
+ * Does `value` reference an instance of the resource type `type` —
+ * either a locally-declared resource or a `Resource.ref(...)` to one?
+ *
+ * Two constraints that ad-hoc guards get wrong for refs, which resolve
+ * to Output-expression proxies:
+ *
+ * - Read `.Type` via property access (never `in`): the proxy answers
+ *   property reads with statically-known values but deliberately does
+ *   not report key existence (so {@link isResource} keeps routing refs
+ *   through Output resolution instead of the upstream-node lookup).
+ * - Accept `typeof value === "function"`: the proxy's target is
+ *   callable (it needs an `apply` trap), so refs are not `"object"`.
+ *
+ * Either mistake silently rejects refs — in a Worker `env` that
+ * degrades the binding to a plain JSON var.
+ */
+export const isResourceOfType = (value: unknown, type: string): boolean =>
+  (typeof value === "object" || typeof value === "function") &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === type;
+
 export type Resource<
   Type extends string = any,
   Props extends object | undefined = any,
@@ -162,6 +193,23 @@ export interface ResourceOptions {
    * @default "destroy"
    */
   defaultRemovalPolicy?: RemovalPolicy["Service"];
+  /**
+   * Legacy type names this resource was previously registered under.
+   *
+   * When a resource type is renamed (e.g. `"Cloudflare.Queue"` →
+   * `"Cloudflare.Queues.Queue"`), state persisted under the old name must
+   * still resolve to this resource's provider. Listing the old names here
+   * makes provider lookup fall back from the legacy name to this type, so
+   * existing stacks keep planning, updating, and deleting cleanly across
+   * the rename. The state row migrates to the new type on its next write.
+   *
+   * ```ts
+   * export const Queue = Resource<Queue>("Cloudflare.Queues.Queue", {
+   *   aliases: ["Cloudflare.Queue"],
+   * });
+   * ```
+   */
+  aliases?: string[];
 }
 
 /**
@@ -312,11 +360,12 @@ export function Resource<R extends ResourceLike>(
       id: string,
       options?: { stage?: string; stack?: string },
     ): Effect.Effect<R> =>
-      Effect.succeed(Output.of(makeRef<R>(id, options)) as unknown as R),
+      Effect.succeed(Output.of(makeRef<R>(id, options, type)) as unknown as R),
 
     Type: type,
     Provider: ProviderTag,
     Self: self,
+    Aliases: options?.aliases,
   };
 
   const ResourceClass = Object.assign(

package/src/Stack.ts

@@ -238,7 +238,7 @@ export const make =
                 `    providers: Cloudflare.providers(),\n` +
                 `    state: Cloudflare.state(), // <-- required\n` +
                 `  }, ...)\n` +
-                `See https://v2.alchemy.run/concepts/state-store for available state stores.`,
+                `See https://v2.alchemy.run/state-store for available state stores.`,
             ),
           );
         }

package/src/State/HttpStateStore.ts

@@ -59,10 +59,15 @@ export const checkHttpStateStoreAuth = ({
       Effect.retry({
         while: (error) =>
           error._tag === "HttpClientError" &&
-          !!error.response &&
-          // worker can 404 for a bit on first deploy
-          (error.response.status === 404 || error.response.status >= 500),
-        schedule: Schedule.fixed(200),
+          // transport-level failures (no response — DNS, TCP reset, TLS,
+          // "fetch failed") are as transient as the post-deploy 404s
+          (!error.response ||
+            // worker can 404 for a bit on first deploy
+            error.response.status === 404 ||
+            error.response.status >= 500),
+        // Bounded: a store that 404s/500s forever is a hard failure, not
+        // something to spin on until the process is killed.
+        schedule: Schedule.max([Schedule.fixed(200), Schedule.recurs(75)]),
       }),
     );
   });
@@ -220,12 +225,49 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
     // Exponential backoff capped at 2s, max 5 attempts. Beyond that
     // the issue isn't transient and we'd rather surface a hard
     // failure than block the deploy indefinitely.
-    schedule: Schedule.exponential(100).pipe(
-      Schedule.either(Schedule.spaced("2 seconds")),
-      Schedule.both(Schedule.recurs(5)),
-    ),
+    schedule: Schedule.max([
+      Schedule.min([Schedule.exponential(100), Schedule.spaced("2 seconds")]),
+      Schedule.recurs(5),
+    ]),
   });
 
+/**
+ * Human-readable description of a state-store client failure.
+ *
+ * Several of the errors the HTTP client can raise carry an empty
+ * `message` (e.g. the no-content `Unauthorized` the store returns on a
+ * bad bearer token), which used to surface as a blank
+ * `StateStoreError` with nothing to act on. Always produce a
+ * non-empty message: prefer the error's own message, fall back to its
+ * `_tag`/name, and append the HTTP status and any distinct `cause`
+ * message when available.
+ */
+export const describeStateStoreFailure = (e: unknown): string => {
+  if (!(e instanceof Error)) return String(e);
+  const tag = (e as { _tag?: unknown })._tag;
+  let message =
+    e.message.trim() ||
+    (typeof tag === "string" ? tag : undefined) ||
+    e.name ||
+    "Unknown error";
+  if (typeof tag === "string" && tag.startsWith("Unauthorized")) {
+    message =
+      "State store rejected the request as unauthorized. " +
+      "The stored state-store credentials may be stale — run 'alchemy login' to refresh them.";
+  }
+  const status = (e as { response?: { status?: unknown } }).response?.status;
+  if (typeof status === "number" && !message.includes(String(status))) {
+    message += ` (HTTP ${status})`;
+  }
+  if (e.cause instanceof Error) {
+    const causeMessage = e.cause.message.trim();
+    if (causeMessage && !message.includes(causeMessage)) {
+      message += ` — caused by: ${causeMessage}`;
+    }
+  }
+  return message;
+};
+
 /** Collapse any client failure into a {@link StateStoreError}. */
 const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
   eff.pipe(
@@ -234,7 +276,7 @@ const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
     Effect.catch((e: E) =>
       Effect.fail(
         new StateStoreError({
-          message: e instanceof Error ? e.message : String(e),
+          message: describeStateStoreFailure(e),
           cause: e instanceof Error ? e : undefined,
         }),
       ),