alchemy 2.0.0-beta.57 → 2.0.0-beta.59

package/src/Cloudflare/Flagship/Flag.ts

@@ -9,13 +9,13 @@ import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
 
-const FlagshipFlagTypeId = "Cloudflare.Flagship.Flag" as const;
-type FlagshipFlagTypeId = typeof FlagshipFlagTypeId;
+const TypeId = "Cloudflare.Flagship.Flag" as const;
+type TypeId = typeof TypeId;
 
 /**
  * Comparison operator applied to a targeting condition.
  */
-export type FlagshipFlagConditionOperator =
+export type FlagConditionOperator =
   | "equals"
   | "not_equals"
   | "greater_than"
@@ -32,7 +32,7 @@ export type FlagshipFlagConditionOperator =
  * A single targeting condition: either a flat attribute comparison or a
  * nested group of clauses combined with AND/OR.
  */
-export type FlagshipFlagCondition =
+export type FlagCondition =
   | {
       /**
        * Evaluation-context attribute to match on (e.g. `country`, `userId`).
@@ -41,7 +41,7 @@ export type FlagshipFlagCondition =
       /**
        * Comparison operator.
        */
-      operator: FlagshipFlagConditionOperator;
+      operator: FlagConditionOperator;
       /**
        * Value to compare against.
        */
@@ -51,7 +51,7 @@ export type FlagshipFlagCondition =
       /**
        * Nested conditions combined with `logicalOperator`.
        */
-      clauses: FlagshipFlagCondition[];
+      clauses: FlagCondition[];
       /**
        * How the clauses combine.
        */
@@ -61,7 +61,7 @@ export type FlagshipFlagCondition =
 /**
  * Percentage rollout applied after a rule's conditions match.
  */
-export type FlagshipFlagRollout = {
+export type FlagRollout = {
   /**
    * Percentage of matching contexts served the rule's variation (0-100).
    */
@@ -77,11 +77,11 @@ export type FlagshipFlagRollout = {
  * A targeting rule. Rules are evaluated in ascending `priority`; the first
  * matching rule wins.
  */
-export type FlagshipFlagRule = {
+export type FlagRule = {
   /**
    * Conditions that must all match for the rule to apply.
    */
-  conditions: FlagshipFlagCondition[];
+  conditions: FlagCondition[];
   /**
    * Evaluation order — lower runs first.
    */
@@ -93,15 +93,15 @@ export type FlagshipFlagRule = {
   /**
    * Optional percentage rollout applied after the conditions match.
    */
-  rollout?: FlagshipFlagRollout;
+  rollout?: FlagRollout;
 };
 
 /**
  * Value type of a flag's variations.
  */
-export type FlagshipFlagType = "boolean" | "string" | "number" | "json";
+export type FlagType = "boolean" | "string" | "number" | "json";
 
-export type FlagshipFlagProps = {
+export type FlagProps = {
   /**
    * The Flagship app the flag belongs to. Changing the app triggers a
    * replacement.
@@ -137,7 +137,7 @@ export type FlagshipFlagProps = {
    * `defaultVariation`.
    * @default []
    */
-  rules?: FlagshipFlagRule[];
+  rules?: FlagRule[];
   /**
    * Human readable description of the flag.
    */
@@ -146,10 +146,10 @@ export type FlagshipFlagProps = {
    * Value type of the flag's variations. Inferred from the variation values
    * on write, so it can usually be omitted.
    */
-  type?: FlagshipFlagType;
+  type?: FlagType;
 };
 
-export type FlagshipFlagAttributes = {
+export type FlagAttributes = {
   /**
    * The Flagship app the flag belongs to.
    */
@@ -177,7 +177,7 @@ export type FlagshipFlagAttributes = {
   /**
    * Targeting rules.
    */
-  rules: FlagshipFlagRule[];
+  rules: FlagRule[];
   /**
    * Human readable description of the flag.
    */
@@ -185,7 +185,7 @@ export type FlagshipFlagAttributes = {
   /**
    * Value type of the flag's variations, as inferred by Cloudflare.
    */
-  type: FlagshipFlagType | undefined;
+  type: FlagType | undefined;
   /**
    * When the flag was last modified.
    */
@@ -197,10 +197,10 @@ export type FlagshipFlagAttributes = {
   updatedBy: string | undefined;
 };
 
-export type FlagshipFlag = Resource<
-  FlagshipFlagTypeId,
-  FlagshipFlagProps,
-  FlagshipFlagAttributes,
+export type Flag = Resource<
+  TypeId,
+  FlagProps,
+  FlagAttributes,
   never,
   Providers
 >;
@@ -219,9 +219,9 @@ export type FlagshipFlag = Resource<
  * @section Creating a Flag
  * @example Boolean flag
  * ```typescript
- * const app = yield* Cloudflare.FlagshipApp("Flags", {});
+ * const app = yield* Cloudflare.Flagship.App("Flags", {});
  *
- * const flag = yield* Cloudflare.FlagshipFlag("NewCheckout", {
+ * const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
  *   appId: app.appId,
  *   key: "new-checkout",
  *   defaultVariation: "off",
@@ -231,7 +231,7 @@ export type FlagshipFlag = Resource<
  *
  * @example String flag with multiple variations
  * ```typescript
- * const flag = yield* Cloudflare.FlagshipFlag("CheckoutFlow", {
+ * const flag = yield* Cloudflare.Flagship.Flag("CheckoutFlow", {
  *   appId: app.appId,
  *   key: "checkout-flow",
  *   defaultVariation: "v1",
@@ -242,7 +242,7 @@ export type FlagshipFlag = Resource<
  * @section Targeting Rules
  * @example Serve a variation to a specific country
  * ```typescript
- * const flag = yield* Cloudflare.FlagshipFlag("DarkMode", {
+ * const flag = yield* Cloudflare.Flagship.Flag("DarkMode", {
  *   appId: app.appId,
  *   key: "dark-mode",
  *   defaultVariation: "off",
@@ -261,7 +261,7 @@ export type FlagshipFlag = Resource<
  *
  * @example Percentage rollout
  * ```typescript
- * const flag = yield* Cloudflare.FlagshipFlag("NewSearch", {
+ * const flag = yield* Cloudflare.Flagship.Flag("NewSearch", {
  *   appId: app.appId,
  *   key: "new-search",
  *   defaultVariation: "off",
@@ -280,7 +280,7 @@ export type FlagshipFlag = Resource<
  * @section Toggling a Flag
  * @example Disable a flag without removing its rules
  * ```typescript
- * const flag = yield* Cloudflare.FlagshipFlag("NewCheckout", {
+ * const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
  *   appId: app.appId,
  *   key: "new-checkout",
  *   enabled: false,
@@ -292,16 +292,16 @@ export type FlagshipFlag = Resource<
  * @see https://developers.cloudflare.com/flagship/
  * @see https://developers.cloudflare.com/api/resources/flagship/
  */
-export const FlagshipFlag = Resource<FlagshipFlag>(FlagshipFlagTypeId);
+export const Flag = Resource<Flag>(TypeId);
 
 /**
- * Returns true if the given value is a FlagshipFlag resource.
+ * Returns true if the given value is a Flagship Flag resource.
  */
-export const isFlagshipFlag = (value: unknown): value is FlagshipFlag =>
-  Predicate.hasProperty(value, "Type") && value.Type === FlagshipFlagTypeId;
+export const isFlag = (value: unknown): value is Flag =>
+  Predicate.hasProperty(value, "Type") && value.Type === TypeId;
 
-export const FlagshipFlagProvider = () =>
-  Provider.succeed(FlagshipFlag, {
+export const FlagProvider = () =>
+  Provider.succeed(Flag, {
     stables: ["appId", "accountId", "key"],
     diff: Effect.fn(function* ({ olds, news, output }) {
       if (!isResolved(news)) return undefined;
@@ -456,7 +456,7 @@ export const FlagshipFlagProvider = () =>
             // The parent app can be deleted between enumeration and the
             // per-app flag list; treat a gone app as having no flags.
             Effect.catchTag("FlagshipAppNotFound", () =>
-              Effect.succeed<FlagshipFlagAttributes[]>([]),
+              Effect.succeed<FlagAttributes[]>([]),
             ),
           ),
         { concurrency: 10 },
@@ -487,9 +487,7 @@ const createFlagKey = (id: string, key: string | undefined) =>
  * Wire rules carry readonly markers, open-union widening, and explicit
  * nulls; strip them so rules diff structurally against the user's props.
  */
-const normalizeRules = (
-  rules: readonly WireRule[] | FlagshipFlagRule[],
-): FlagshipFlagRule[] =>
+const normalizeRules = (rules: readonly WireRule[] | FlagRule[]): FlagRule[] =>
   rules.map((rule) => ({
     conditions: normalizeConditions(rule.conditions),
     priority: rule.priority,
@@ -513,10 +511,8 @@ type WireRule = {
   rollout?: { percentage: number; attribute?: string | null } | null;
 };
 
-const normalizeConditions = (
-  conditions: readonly unknown[],
-): FlagshipFlagCondition[] =>
-  conditions.flatMap((condition): FlagshipFlagCondition[] => {
+const normalizeConditions = (conditions: readonly unknown[]): FlagCondition[] =>
+  conditions.flatMap((condition): FlagCondition[] => {
     if (Predicate.hasProperty(condition, "clauses")) {
       const group = condition as {
         clauses: readonly unknown[];
@@ -538,7 +534,7 @@ const normalizeConditions = (
       return [
         {
           attribute: flat.attribute,
-          operator: flat.operator as FlagshipFlagConditionOperator,
+          operator: flat.operator as FlagConditionOperator,
           value: flat.value,
         },
       ];
@@ -554,7 +550,7 @@ const toAttributes = (
     | flagship.ListAppFlagsResponse["result"][number],
   accountId: string,
   appId: string,
-): FlagshipFlagAttributes => ({
+): FlagAttributes => ({
   appId,
   accountId,
   key: flag.key,
@@ -563,7 +559,7 @@ const toAttributes = (
   variations: flag.variations,
   rules: normalizeRules(flag.rules),
   description: flag.description ?? undefined,
-  type: (flag.type as FlagshipFlagType | null | undefined) ?? undefined,
+  type: (flag.type as FlagType | null | undefined) ?? undefined,
   updatedAt: flag.updatedAt ?? undefined,
   updatedBy: flag.updatedBy ?? undefined,
 });

package/src/Cloudflare/Flagship/ReadFlags.ts

@@ -0,0 +1,145 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Binding from "../../Binding.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import type { App } from "./App.ts";
+
+/**
+ * Bind a {@link App} to a Worker and obtain the Effect-native flag-evaluation
+ * client (`get`, `getBooleanValue`, `getStringValue`, …).
+ *
+ * `ReadFlags` is a single identifier that is simultaneously the binding's
+ * Context tag, its type, and the callable —
+ * `yield* Cloudflare.Flagship.ReadFlags(app)`.
+ *
+ * @example Evaluating a flag inside a Worker
+ * ```typescript
+ * const flags = yield* Cloudflare.Flagship.ReadFlags(MyApp);
+ * const enabled = yield* flags.getBooleanValue("new-checkout", false);
+ * ```
+ *
+ * @binding
+ * @product Flagship
+ * @category Developer Platform
+ */
+export interface ReadFlags extends Binding.Service<
+  ReadFlags,
+  "Cloudflare.Flagship.ReadFlags",
+  (app: App) => Effect.Effect<ReadFlagsClient>
+> {}
+
+export const ReadFlags = Binding.Service<ReadFlags>(
+  "Cloudflare.Flagship.ReadFlags",
+);
+
+export class FlagshipError extends Data.TaggedError("FlagshipError")<{
+  message: string;
+  cause: unknown;
+}> {}
+
+/** An Effect produced by a {@link ReadFlagsClient} operation. */
+type FlagshipEffect<A> = Effect.Effect<A, FlagshipError, RuntimeContext>;
+
+// Re-exported so callers don't reach into the `@cloudflare/workers-types`
+// namespace directly.
+export type EvaluationContext = cf.FlagshipEvaluationContext;
+export type EvaluationDetails<T> = cf.FlagshipEvaluationDetails<T>;
+
+/**
+ * Effect-native client for a Cloudflare Flagship (feature flags) binding.
+ *
+ * Mirrors the runtime {@link cf.Flagship} binding one-to-one, translating each
+ * promise-returning method into an Effect. Flagship evaluation never throws —
+ * it falls back to the provided `defaultValue` — so the {@link FlagshipError}
+ * channel only surfaces unexpected runtime failures (e.g. a misconfigured
+ * binding). Use `Cloudflare.Flagship.ReadFlags(app)` inside a Worker's init
+ * phase to obtain it.
+ */
+export interface ReadFlagsClient {
+  /**
+   * Effect resolving to the raw Cloudflare Flagship runtime binding.
+   */
+  raw: Effect.Effect<cf.Flagship, never, RuntimeContext>;
+  /**
+   * Get a flag value without type checking. Use when the flag type is not
+   * known at compile time.
+   */
+  get(
+    flagKey: string,
+    defaultValue?: unknown,
+    context?: EvaluationContext,
+  ): FlagshipEffect<unknown>;
+  /**
+   * Get a boolean flag value, falling back to `defaultValue` when evaluation
+   * fails or the flag type does not match.
+   */
+  getBooleanValue(
+    flagKey: string,
+    defaultValue: boolean,
+    context?: EvaluationContext,
+  ): FlagshipEffect<boolean>;
+  /**
+   * Get a string flag value, falling back to `defaultValue` when evaluation
+   * fails or the flag type does not match.
+   */
+  getStringValue(
+    flagKey: string,
+    defaultValue: string,
+    context?: EvaluationContext,
+  ): FlagshipEffect<string>;
+  /**
+   * Get a number flag value, falling back to `defaultValue` when evaluation
+   * fails or the flag type does not match.
+   */
+  getNumberValue(
+    flagKey: string,
+    defaultValue: number,
+    context?: EvaluationContext,
+  ): FlagshipEffect<number>;
+  /**
+   * Get a typed object flag value, falling back to `defaultValue` when
+   * evaluation fails or the flag type does not match.
+   */
+  getObjectValue<T extends object>(
+    flagKey: string,
+    defaultValue: T,
+    context?: EvaluationContext,
+  ): FlagshipEffect<T>;
+  /**
+   * Get a boolean flag value with full evaluation details (variant, reason,
+   * error code).
+   */
+  getBooleanDetails(
+    flagKey: string,
+    defaultValue: boolean,
+    context?: EvaluationContext,
+  ): FlagshipEffect<EvaluationDetails<boolean>>;
+  /**
+   * Get a string flag value with full evaluation details (variant, reason,
+   * error code).
+   */
+  getStringDetails(
+    flagKey: string,
+    defaultValue: string,
+    context?: EvaluationContext,
+  ): FlagshipEffect<EvaluationDetails<string>>;
+  /**
+   * Get a number flag value with full evaluation details (variant, reason,
+   * error code).
+   */
+  getNumberDetails(
+    flagKey: string,
+    defaultValue: number,
+    context?: EvaluationContext,
+  ): FlagshipEffect<EvaluationDetails<number>>;
+  /**
+   * Get a typed object flag value with full evaluation details (variant,
+   * reason, error code).
+   */
+  getObjectDetails<T extends object>(
+    flagKey: string,
+    defaultValue: T,
+    context?: EvaluationContext,
+  ): FlagshipEffect<EvaluationDetails<T>>;
+}

package/src/Cloudflare/Flagship/ReadFlagsBinding.ts

@@ -0,0 +1,78 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import { Worker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { App } from "./App.ts";
+import { FlagshipError, ReadFlags, type ReadFlagsClient } from "./ReadFlags.ts";
+
+export const ReadFlagsBinding = Layer.effect(
+  ReadFlags,
+  Effect.gen(function* () {
+    const env = yield* WorkerEnvironment;
+    const host = yield* Worker;
+
+    return Effect.fn(function* (app: App) {
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        yield* host.bind(app.LogicalId, {
+          bindings: [
+            {
+              type: "flagship",
+              name: app.LogicalId,
+              appId: app.appId,
+            },
+          ],
+        });
+      }
+      const raw: Effect.Effect<cf.Flagship, never, RuntimeContext> =
+        Effect.sync(() => (env as Record<string, cf.Flagship>)[app.LogicalId]!);
+      return makeFlagshipClient(raw);
+    });
+  }),
+);
+
+/** An Effect produced by a {@link ReadFlagsClient} operation. */
+type FlagshipEffect<A> = Effect.Effect<A, FlagshipError, RuntimeContext>;
+
+const tryPromise = <T>(fn: () => Promise<T>): Effect.Effect<T, FlagshipError> =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (error) =>
+      new FlagshipError({
+        message:
+          error instanceof Error ? error.message : "Unknown Flagship error",
+        cause: error,
+      }),
+  });
+
+/** @internal */
+export const makeFlagshipClient = (
+  raw: Effect.Effect<cf.Flagship, never, RuntimeContext>,
+): ReadFlagsClient => {
+  const call = <T>(
+    fn: (binding: cf.Flagship) => Promise<T>,
+  ): FlagshipEffect<T> =>
+    raw.pipe(Effect.flatMap((binding) => tryPromise(() => fn(binding))));
+
+  return {
+    raw,
+    get: (flagKey, defaultValue, context) =>
+      call((b) => b.get(flagKey, defaultValue, context)),
+    getBooleanValue: (flagKey, defaultValue, context) =>
+      call((b) => b.getBooleanValue(flagKey, defaultValue, context)),
+    getStringValue: (flagKey, defaultValue, context) =>
+      call((b) => b.getStringValue(flagKey, defaultValue, context)),
+    getNumberValue: (flagKey, defaultValue, context) =>
+      call((b) => b.getNumberValue(flagKey, defaultValue, context)),
+    getObjectValue: (flagKey, defaultValue, context) =>
+      call((b) => b.getObjectValue(flagKey, defaultValue, context)),
+    getBooleanDetails: (flagKey, defaultValue, context) =>
+      call((b) => b.getBooleanDetails(flagKey, defaultValue, context)),
+    getStringDetails: (flagKey, defaultValue, context) =>
+      call((b) => b.getStringDetails(flagKey, defaultValue, context)),
+    getNumberDetails: (flagKey, defaultValue, context) =>
+      call((b) => b.getNumberDetails(flagKey, defaultValue, context)),
+    getObjectDetails: (flagKey, defaultValue, context) =>
+      call((b) => b.getObjectDetails(flagKey, defaultValue, context)),
+  } satisfies ReadFlagsClient;
+};

package/src/Cloudflare/Flagship/index.ts

@@ -1,12 +1,10 @@
 export * from "./App.ts";
 export * from "./Flag.ts";
 export {
-  FlagshipBinding,
-  FlagshipBindingLive,
-  FlagshipBindingPolicy,
-  FlagshipBindingPolicyLive,
+  ReadFlags,
   FlagshipError,
-  type FlagshipClient,
-  type FlagshipEvaluationContext,
-  type FlagshipEvaluationDetails,
-} from "./FlagshipBinding.ts";
+  type ReadFlagsClient,
+  type EvaluationContext,
+  type EvaluationDetails,
+} from "./ReadFlags.ts";
+export { ReadFlagsBinding } from "./ReadFlagsBinding.ts";