@stratal/feature-flags 0.0.21

package/README.md

@@ -0,0 +1,54 @@
+# @stratal/feature-flags
+
+[Cloudflare Flagship](https://developers.cloudflare.com/flagship/) feature flags for the [Stratal](https://stratal.dev) framework, using the native Worker **binding API** — with zero-config [Inertia.js](https://inertiajs.com) auto-sharing and typed React hooks.
+
+## Install
+
+```bash
+npm i @stratal/feature-flags
+```
+
+Add the Flagship binding to your Wrangler config and run `npx wrangler types`:
+
+```jsonc
+// wrangler.jsonc
+{ "flagship": [{ "binding": "FLAGS", "app_id": "<APP_ID>" }] }
+```
+
+## Usage
+
+```ts
+import { FeatureFlagModule } from '@stratal/feature-flags'
+
+@Module({
+  imports: [
+    FeatureFlagModule.forRoot({
+      apps: [{ binding: 'FLAGS', flags: { 'new-checkout': false } }],
+      context: (ctx) => ({ userId: ctx.user().id }), // ctx.user() from @stratal/framework
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+When `@stratal/inertia` is installed, declared flags are auto-shared to every Inertia page — no extra wiring.
+
+Evaluate on the server:
+
+```ts
+const enabled = await this.flags.getBooleanValue('new-checkout') // uses manifest default
+```
+
+Read on the client:
+
+```tsx
+import { useFlag } from '@stratal/feature-flags/react'
+
+const showNewCheckout = useFlag('new-checkout')
+```
+
+See the framework docs for the full API.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,166 @@
+import { a as FlagValue, i as FlagManifest, n as FeatureFlagModuleOptions, o as FlagshipBindingName, r as FeatureFlagRegistry, t as FeatureFlagApp } from "./types-Dxuc-7SJ.mjs";
+import { AsyncModuleOptions, DynamicModule } from "stratal/module";
+import { Middleware, Next, RouteConfigurable, Router, RouterContext } from "stratal/router";
+import { ApplicationError } from "stratal/errors";
+import { StratalEnv } from "stratal";
+
+//#region src/feature-flags.module.d.ts
+/**
+ * Feature Flag Module
+ *
+ * Evaluates Cloudflare Flagship feature flags through the native Worker binding.
+ * Declare your apps (and the flags you use) once; inject {@link FeatureFlagService}
+ * to evaluate them.
+ *
+ * When `@stratal/inertia` is also present, declared flags are auto-shared to
+ * every Inertia page as the `featureFlags` prop (read them with `useFlag` /
+ * `useFeatureFlags` from `@stratal/feature-flags/react`) — no extra wiring. In
+ * a pure-API worker the auto-share middleware is a no-op.
+ *
+ * @example
+ * ```typescript
+ * FeatureFlagModule.forRoot({
+ *   apps: [{ binding: 'FLAGS', flags: { 'new-checkout': false } }],
+ *   context: (ctx) => ({ userId: ctx.user().id }), // ctx.user() from @stratal/framework
+ * })
+ *
+ * // Or async, from config namespaces:
+ * FeatureFlagModule.forRootAsync({
+ *   inject: [flagsConfig.KEY],
+ *   useFactory: (cfg) => ({ apps: cfg.apps, default: cfg.default }),
+ * })
+ * ```
+ */
+declare class FeatureFlagModule implements RouteConfigurable {
+  /** Auto-shares declared flags to every Inertia page (no-op without Inertia). */
+  configureRoutes(router: Router): void;
+  /** Configure with static options. */
+  static forRoot(options: FeatureFlagModuleOptions): DynamicModule;
+  /** Configure with an async factory (when options depend on other services). */
+  static forRootAsync(options: AsyncModuleOptions<FeatureFlagModuleOptions>): DynamicModule;
+}
+//#endregion
+//#region src/services/feature-flag.service.d.ts
+/**
+ * Feature Flag Service
+ *
+ * Type-safe wrapper around a Cloudflare Flagship binding (`env.FLAGS`). Mirrors
+ * the binding's evaluation methods 1:1, with two ergonomic additions:
+ *
+ * - **Manifest defaults** — when you omit a default, the value declared in the
+ *   app's `flags` manifest is used (an explicit argument always wins).
+ * - **Default context** — the module's `context` resolver is merged into every
+ *   evaluation (per-call context overrides it). Resolved from the current
+ *   request; skipped automatically outside request scope.
+ *
+ * Switch to another Flagship app with {@link use}. Evaluation never throws — the
+ * binding returns the default value on error.
+ *
+ * @example
+ * ```typescript
+ * @inject(FEATURE_FLAG_TOKENS.FeatureFlagService)
+ * private readonly flags: FeatureFlagService
+ *
+ * const enabled = await this.flags.getBooleanValue('new-checkout')        // manifest default
+ * const layout  = await this.flags.use('EXPERIMENT_FLAGS').getStringValue('layout', 'v1')
+ * ```
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/
+ */
+declare class FeatureFlagService {
+  private readonly options;
+  private readonly env;
+  private readonly routerContext;
+  private readonly apps;
+  private bindingName;
+  private binding;
+  private manifest;
+  constructor(options: FeatureFlagModuleOptions, env: StratalEnv, routerContext: RouterContext | null);
+  /**
+   * Switch to a different configured Flagship app.
+   *
+   * Returns a new immutable instance bound to `binding`; the original is
+   * unchanged. The binding must be declared in the module's `apps`.
+   */
+  use(binding: FlagshipBindingName): FeatureFlagService;
+  /** The binding name this instance currently targets. */
+  get app(): string;
+  /** Returns the raw flag value without type checking. */
+  get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown>;
+  /** Returns the flag value as a `boolean`. */
+  getBooleanValue(flagKey: string, defaultValue?: boolean, context?: FlagshipEvaluationContext): Promise<boolean>;
+  /** Returns the flag value as a `string`. */
+  getStringValue(flagKey: string, defaultValue?: string, context?: FlagshipEvaluationContext): Promise<string>;
+  /** Returns the flag value as a `number`. */
+  getNumberValue(flagKey: string, defaultValue?: number, context?: FlagshipEvaluationContext): Promise<number>;
+  /** Returns the flag value as a typed object. */
+  getObjectValue<T extends object>(flagKey: string, defaultValue?: T, context?: FlagshipEvaluationContext): Promise<T>;
+  /** Returns the `boolean` flag value with evaluation metadata. */
+  getBooleanDetails(flagKey: string, defaultValue?: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>>;
+  /** Returns the `string` flag value with evaluation metadata. */
+  getStringDetails(flagKey: string, defaultValue?: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>>;
+  /** Returns the `number` flag value with evaluation metadata. */
+  getNumberDetails(flagKey: string, defaultValue?: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>>;
+  /** Returns the typed object flag value with evaluation metadata. */
+  getObjectDetails<T extends object>(flagKey: string, defaultValue?: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>>;
+  /**
+   * Evaluates every flag declared in the current app's manifest and returns a
+   * `{ key: value }` map. The evaluation method is chosen from each declared
+   * default's type. Powers the Inertia auto-share.
+   */
+  all(context?: FlagshipEvaluationContext): Promise<Record<string, FlagValue>>;
+  private bindTo;
+  /** Resolves the merged evaluation context (default context + per-call override). */
+  private context;
+  /** Picks the default: explicit arg, then manifest, then the type's zero value. */
+  private fallback;
+  /** Evaluates a single flag, choosing the method from the declared default's type. */
+  private evaluate;
+}
+//#endregion
+//#region src/feature-flag-share.middleware.d.ts
+declare module 'stratal/router' {
+  interface RouterContext {
+    share(key: string, value: unknown): void;
+  }
+}
+/**
+ * Evaluates the declared flag manifest for the default app and shares it as the
+ * `featureFlags` prop on every Inertia page rendered during the request.
+ *
+ * Only runs on `GET` requests — page renders (full visits and partial reloads)
+ * are always `GET`, so mutating API calls don't trigger evaluation. No-ops when
+ * Inertia is not installed (`ctx.share` absent), so `FeatureFlagModule` is safe
+ * in pure-API workers. Registered by `FeatureFlagModule`.
+ */
+declare class FeatureFlagShareMiddleware implements Middleware {
+  private readonly flags;
+  constructor(flags: FeatureFlagService);
+  handle(ctx: RouterContext, next: Next): Promise<void>;
+}
+//#endregion
+//#region src/feature-flags.tokens.d.ts
+/**
+ * DI tokens for the feature-flags module.
+ *
+ * Use `Symbol.for(...)` so the tokens resolve to the same symbol across module
+ * boundaries (the global symbol registry).
+ */
+declare const FEATURE_FLAG_TOKENS: {
+  /** The resolved {@link FeatureFlagModuleOptions}. */readonly Options: symbol; /** The request-scoped {@link FeatureFlagService} bound to the default app. */
+  readonly FeatureFlagService: symbol;
+};
+type FeatureFlagToken = (typeof FEATURE_FLAG_TOKENS)[keyof typeof FEATURE_FLAG_TOKENS];
+//#endregion
+//#region src/feature-flags.error.d.ts
+/**
+ * Thrown for feature-flag misconfiguration — an unknown app or a Flagship
+ * binding that is not present on the Worker environment.
+ *
+ * Note: flag *evaluation* never throws; the binding returns the supplied
+ * default value on error.
+ */
+declare class FeatureFlagError extends ApplicationError {}
+//#endregion
+export { FEATURE_FLAG_TOKENS, type FeatureFlagApp, FeatureFlagError, FeatureFlagModule, type FeatureFlagModuleOptions, type FeatureFlagRegistry, FeatureFlagService, FeatureFlagShareMiddleware, type FeatureFlagToken, type FlagManifest, type FlagValue, type FlagshipBindingName };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/feature-flags.module.ts","../src/services/feature-flag.service.ts","../src/feature-flag-share.middleware.ts","../src/feature-flags.tokens.ts","../src/feature-flags.error.ts"],"mappings":";;;;;;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;cAKa,iBAAA,YAA6B,iBAAA;EAiBpB;EAfpB,eAAA,CAAgB,MAAA,EAAQ,MAAA;EAeiE;EAAA,OAVlF,OAAA,CAAQ,OAAA,EAAS,wBAAA,GAA2B,aAAA;;SAU5C,YAAA,CAAa,OAAA,EAAS,kBAAA,CAAmB,wBAAA,IAA4B,aAAA;AAAA;;;;;;;AAtB9E;;;;;;;;;;;;;;;;;;;;;;cCMa,kBAAA;EAAA,iBAO6C,OAAA;EAAA,iBACJ,GAAA;EAAA,iBACI,aAAA;EAAA,iBARvC,IAAA;EAAA,QACT,WAAA;EAAA,QACA,OAAA;EAAA,QACA,QAAA;cAGgD,OAAA,EAAS,wBAAA,EACb,GAAA,EAAK,UAAA,EACD,aAAA,EAAe,aAAA;EAT1C;;;;;;EAuB7B,GAAA,CAAI,OAAA,EAAS,mBAAA,GAAsB,kBAAA;EAe0B;EAAA,IAPzD,GAAA,CAAA;EAYqE;EALnE,GAAA,CAAI,OAAA,UAAiB,YAAA,YAAwB,OAAA,GAAU,yBAAA,GAA4B,OAAA;EAUlB;EALjE,eAAA,CAAgB,OAAA,UAAiB,YAAA,YAAwB,OAAA,GAAU,yBAAA,GAA4B,OAAA;EAU9B;EALjE,cAAA,CAAe,OAAA,UAAiB,YAAA,WAAuB,OAAA,GAAU,yBAAA,GAA4B,OAAA;EAU5B;EALjE,cAAA,CAAe,OAAA,UAAiB,YAAA,WAAuB,OAAA,GAAU,yBAAA,GAA4B,OAAA;EAKqB;EAAlH,cAAA,kBAAA,CAAiC,OAAA,UAAiB,YAAA,GAAe,CAAA,EAAG,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,CAAA;EAK7C;EAArE,iBAAA,CAAkB,OAAA,UAAiB,YAAA,YAAwB,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,yBAAA;EAAR;EAKjG,gBAAA,CAAiB,OAAA,UAAiB,YAAA,WAAuB,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,yBAAA;EAAA;EAKvG,gBAAA,CAAiB,OAAA,UAAiB,YAAA,WAAuB,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,yBAAA;EAApC;EAKnE,gBAAA,kBAAA,CAAmC,OAAA,UAAiB,YAAA,GAAe,CAAA,EAAG,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,yBAAA,CAA0B,CAAA;EAL/C;;;;;EAc/F,GAAA,CAAI,OAAA,GAAU,yBAAA,GAA4B,OAAA,CAAQ,MAAA,SAAe,SAAA;EAAA,QAa/D,MAAA;EAb+D;EAAA,QA+BzD,OAAA;EA/BkC;EAAA,QAsCxC,QAAA;EAtC+C;EAAA,QA6C/C,QAAA;AAAA;;;;YCnKE,aAAA;IACR,KAAA,CAAM,GAAA,UAAa,KAAA;EAAA;AAAA;AFwBvB;;;;;;;;;AAAA,cEVa,0BAAA,YAAsC,UAAA;EAAA,iBAEkB,KAAA;cAAA,KAAA,EAAO,kBAAA;EAGpE,MAAA,CAAO,GAAA,EAAK,aAAA,EAAe,IAAA,EAAM,IAAA,GAAO,OAAA;AAAA;;;;;;;;;cCvBnC,mBAAA;EHiCA,8DG5BH,OAAA;WAAA,kBAAA;AAAA;AAAA,KAEE,gBAAA,WAA2B,mBAAA,eAAkC,mBAAA;;;;;;;;;AHqBzE;cIzBa,gBAAA,SAAyB,gBAAA"}

package/dist/index.mjs

@@ -0,0 +1,233 @@
+import { Module } from "stratal/module";
+import { DI_TOKENS, Request, Transient, inject } from "stratal/di";
+import { ROUTER_TOKENS } from "stratal/router";
+import { ApplicationError } from "stratal/errors";
+//#region src/feature-flags.tokens.ts
+/**
+* DI tokens for the feature-flags module.
+*
+* Use `Symbol.for(...)` so the tokens resolve to the same symbol across module
+* boundaries (the global symbol registry).
+*/
+const FEATURE_FLAG_TOKENS = {
+	/** The resolved {@link FeatureFlagModuleOptions}. */
+	Options: Symbol.for("stratal:feature-flags:options"),
+	/** The request-scoped {@link FeatureFlagService} bound to the default app. */
+	FeatureFlagService: Symbol.for("stratal:feature-flags:service")
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.129.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.129.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.129.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/feature-flag-share.middleware.ts
+let FeatureFlagShareMiddleware = class FeatureFlagShareMiddleware {
+	flags;
+	constructor(flags) {
+		this.flags = flags;
+	}
+	async handle(ctx, next) {
+		if (ctx.c.req.method === "GET" && typeof ctx.share === "function") ctx.share("featureFlags", await this.flags.all());
+		await next();
+	}
+};
+FeatureFlagShareMiddleware = __decorate([
+	Transient(),
+	__decorateParam(0, inject(FEATURE_FLAG_TOKENS.FeatureFlagService)),
+	__decorateMetadata("design:paramtypes", [Object])
+], FeatureFlagShareMiddleware);
+//#endregion
+//#region src/feature-flags.error.ts
+/**
+* Thrown for feature-flag misconfiguration — an unknown app or a Flagship
+* binding that is not present on the Worker environment.
+*
+* Note: flag *evaluation* never throws; the binding returns the supplied
+* default value on error.
+*/
+var FeatureFlagError = class extends ApplicationError {};
+//#endregion
+//#region src/services/feature-flag.service.ts
+var _FeatureFlagService;
+let FeatureFlagService = _FeatureFlagService = class FeatureFlagService {
+	options;
+	env;
+	routerContext;
+	apps = /* @__PURE__ */ new Map();
+	bindingName;
+	binding;
+	manifest;
+	constructor(options, env, routerContext) {
+		this.options = options;
+		this.env = env;
+		this.routerContext = routerContext;
+		for (const app of options.apps) this.apps.set(app.binding, app);
+		this.bindTo(options.default ?? options.apps[0]?.binding);
+	}
+	/**
+	* Switch to a different configured Flagship app.
+	*
+	* Returns a new immutable instance bound to `binding`; the original is
+	* unchanged. The binding must be declared in the module's `apps`.
+	*/
+	use(binding) {
+		if (binding === this.bindingName) return this;
+		const instance = new _FeatureFlagService(this.options, this.env, this.routerContext);
+		instance.bindTo(binding);
+		return instance;
+	}
+	/** The binding name this instance currently targets. */
+	get app() {
+		return this.bindingName;
+	}
+	/** Returns the raw flag value without type checking. */
+	async get(flagKey, defaultValue, context) {
+		return this.binding.get(flagKey, this.fallback(flagKey, defaultValue), await this.context(context));
+	}
+	/** Returns the flag value as a `boolean`. */
+	async getBooleanValue(flagKey, defaultValue, context) {
+		return this.binding.getBooleanValue(flagKey, this.fallback(flagKey, defaultValue, false), await this.context(context));
+	}
+	/** Returns the flag value as a `string`. */
+	async getStringValue(flagKey, defaultValue, context) {
+		return this.binding.getStringValue(flagKey, this.fallback(flagKey, defaultValue, ""), await this.context(context));
+	}
+	/** Returns the flag value as a `number`. */
+	async getNumberValue(flagKey, defaultValue, context) {
+		return this.binding.getNumberValue(flagKey, this.fallback(flagKey, defaultValue, 0), await this.context(context));
+	}
+	/** Returns the flag value as a typed object. */
+	async getObjectValue(flagKey, defaultValue, context) {
+		return this.binding.getObjectValue(flagKey, this.fallback(flagKey, defaultValue, {}), await this.context(context));
+	}
+	/** Returns the `boolean` flag value with evaluation metadata. */
+	async getBooleanDetails(flagKey, defaultValue, context) {
+		return this.binding.getBooleanDetails(flagKey, this.fallback(flagKey, defaultValue, false), await this.context(context));
+	}
+	/** Returns the `string` flag value with evaluation metadata. */
+	async getStringDetails(flagKey, defaultValue, context) {
+		return this.binding.getStringDetails(flagKey, this.fallback(flagKey, defaultValue, ""), await this.context(context));
+	}
+	/** Returns the `number` flag value with evaluation metadata. */
+	async getNumberDetails(flagKey, defaultValue, context) {
+		return this.binding.getNumberDetails(flagKey, this.fallback(flagKey, defaultValue, 0), await this.context(context));
+	}
+	/** Returns the typed object flag value with evaluation metadata. */
+	async getObjectDetails(flagKey, defaultValue, context) {
+		return this.binding.getObjectDetails(flagKey, this.fallback(flagKey, defaultValue, {}), await this.context(context));
+	}
+	/**
+	* Evaluates every flag declared in the current app's manifest and returns a
+	* `{ key: value }` map. The evaluation method is chosen from each declared
+	* default's type. Powers the Inertia auto-share.
+	*/
+	async all(context) {
+		const merged = await this.context(context);
+		const keys = Object.keys(this.manifest);
+		const values = await Promise.all(keys.map((key) => this.evaluate(key, this.manifest[key], merged)));
+		const result = {};
+		keys.forEach((key, i) => {
+			result[key] = values[i];
+		});
+		return result;
+	}
+	bindTo(name) {
+		if (!name) throw new FeatureFlagError("No feature flag apps configured. Provide at least one app in FeatureFlagModule.forRoot({ apps: [...] }).");
+		const app = this.apps.get(name);
+		if (!app) throw new FeatureFlagError(`Feature flag app "${name}" is not configured.`);
+		const binding = this.env[name];
+		if (!binding) throw new FeatureFlagError(`Flagship binding "${name}" was not found in the environment.`);
+		this.bindingName = name;
+		this.binding = binding;
+		this.manifest = app.flags ?? {};
+	}
+	/** Resolves the merged evaluation context (default context + per-call override). */
+	async context(callContext) {
+		if (!this.options.context || !this.routerContext) return callContext;
+		const base = await this.options.context(this.routerContext);
+		return callContext ? {
+			...base,
+			...callContext
+		} : base;
+	}
+	/** Picks the default: explicit arg, then manifest, then the type's zero value. */
+	fallback(flagKey, provided, zero) {
+		if (provided !== void 0) return provided;
+		if (flagKey in this.manifest) return this.manifest[flagKey];
+		return zero;
+	}
+	/** Evaluates a single flag, choosing the method from the declared default's type. */
+	evaluate(flagKey, declared, context) {
+		switch (typeof declared) {
+			case "boolean": return this.binding.getBooleanValue(flagKey, declared, context);
+			case "number": return this.binding.getNumberValue(flagKey, declared, context);
+			case "string": return this.binding.getStringValue(flagKey, declared, context);
+			default: return this.binding.getObjectValue(flagKey, declared, context);
+		}
+	}
+};
+FeatureFlagService = _FeatureFlagService = __decorate([
+	Request(FEATURE_FLAG_TOKENS.FeatureFlagService),
+	__decorateParam(0, inject(FEATURE_FLAG_TOKENS.Options)),
+	__decorateParam(1, inject(DI_TOKENS.CloudflareEnv)),
+	__decorateParam(2, inject(ROUTER_TOKENS.RouterContext)),
+	__decorateMetadata("design:paramtypes", [
+		Object,
+		Object,
+		Object
+	])
+], FeatureFlagService);
+//#endregion
+//#region src/feature-flags.module.ts
+var _FeatureFlagModule;
+let FeatureFlagModule = _FeatureFlagModule = class FeatureFlagModule {
+	/** Auto-shares declared flags to every Inertia page (no-op without Inertia). */
+	configureRoutes(router) {
+		router.use(FeatureFlagShareMiddleware);
+	}
+	/** Configure with static options. */
+	static forRoot(options) {
+		return {
+			module: _FeatureFlagModule,
+			providers: [{
+				provide: FEATURE_FLAG_TOKENS.Options,
+				useValue: options
+			}]
+		};
+	}
+	/** Configure with an async factory (when options depend on other services). */
+	static forRootAsync(options) {
+		return {
+			module: _FeatureFlagModule,
+			providers: [{
+				provide: FEATURE_FLAG_TOKENS.Options,
+				useFactory: options.useFactory,
+				inject: options.inject
+			}]
+		};
+	}
+};
+FeatureFlagModule = _FeatureFlagModule = __decorate([Module({ providers: [{
+	provide: FEATURE_FLAG_TOKENS.FeatureFlagService,
+	useClass: FeatureFlagService
+}] })], FeatureFlagModule);
+//#endregion
+export { FEATURE_FLAG_TOKENS, FeatureFlagError, FeatureFlagModule, FeatureFlagService, FeatureFlagShareMiddleware };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/feature-flags.tokens.ts","../src/feature-flag-share.middleware.ts","../src/feature-flags.error.ts","../src/services/feature-flag.service.ts","../src/feature-flags.module.ts"],"sourcesContent":["/**\n * DI tokens for the feature-flags module.\n *\n * Use `Symbol.for(...)` so the tokens resolve to the same symbol across module\n * boundaries (the global symbol registry).\n */\nexport const FEATURE_FLAG_TOKENS = {\n  /** The resolved {@link FeatureFlagModuleOptions}. */\n  Options: Symbol.for('stratal:feature-flags:options'),\n  /** The request-scoped {@link FeatureFlagService} bound to the default app. */\n  FeatureFlagService: Symbol.for('stratal:feature-flags:service'),\n} as const\n\nexport type FeatureFlagToken = (typeof FEATURE_FLAG_TOKENS)[keyof typeof FEATURE_FLAG_TOKENS]\n","import { Transient, inject } from 'stratal/di'\nimport type { Middleware, Next, RouterContext } from 'stratal/router'\nimport { FEATURE_FLAG_TOKENS } from './feature-flags.tokens'\nimport type { FeatureFlagService } from './services/feature-flag.service'\n\n// `ctx.share` is contributed at runtime by `@stratal/inertia` (an optional peer).\n// Declared here so this package types the call without importing Inertia; the\n// signature matches Inertia's, so the declarations merge when both are present.\ndeclare module 'stratal/router' {\n  interface RouterContext {\n    share(key: string, value: unknown): void\n  }\n}\n\n/**\n * Evaluates the declared flag manifest for the default app and shares it as the\n * `featureFlags` prop on every Inertia page rendered during the request.\n *\n * Only runs on `GET` requests — page renders (full visits and partial reloads)\n * are always `GET`, so mutating API calls don't trigger evaluation. No-ops when\n * Inertia is not installed (`ctx.share` absent), so `FeatureFlagModule` is safe\n * in pure-API workers. Registered by `FeatureFlagModule`.\n */\n@Transient()\nexport class FeatureFlagShareMiddleware implements Middleware {\n  constructor(\n    @inject(FEATURE_FLAG_TOKENS.FeatureFlagService) private readonly flags: FeatureFlagService,\n  ) {}\n\n  async handle(ctx: RouterContext, next: Next): Promise<void> {\n    if (ctx.c.req.method === 'GET' && typeof ctx.share === 'function') {\n      ctx.share('featureFlags', await this.flags.all())\n    }\n    await next()\n  }\n}\n","import { ApplicationError } from 'stratal/errors'\n\n/**\n * Thrown for feature-flag misconfiguration — an unknown app or a Flagship\n * binding that is not present on the Worker environment.\n *\n * Note: flag *evaluation* never throws; the binding returns the supplied\n * default value on error.\n */\nexport class FeatureFlagError extends ApplicationError {}\n","import type { StratalEnv } from 'stratal'\nimport { DI_TOKENS, Request, inject } from 'stratal/di'\nimport { ROUTER_TOKENS, type RouterContext } from 'stratal/router'\nimport { FeatureFlagError } from '../feature-flags.error'\nimport { FEATURE_FLAG_TOKENS } from '../feature-flags.tokens'\nimport type {\n  FeatureFlagApp,\n  FeatureFlagModuleOptions,\n  FlagManifest,\n  FlagValue,\n  FlagshipBindingName,\n} from '../types'\n\n/**\n * Feature Flag Service\n *\n * Type-safe wrapper around a Cloudflare Flagship binding (`env.FLAGS`). Mirrors\n * the binding's evaluation methods 1:1, with two ergonomic additions:\n *\n * - **Manifest defaults** — when you omit a default, the value declared in the\n *   app's `flags` manifest is used (an explicit argument always wins).\n * - **Default context** — the module's `context` resolver is merged into every\n *   evaluation (per-call context overrides it). Resolved from the current\n *   request; skipped automatically outside request scope.\n *\n * Switch to another Flagship app with {@link use}. Evaluation never throws — the\n * binding returns the default value on error.\n *\n * @example\n * ```typescript\n * @inject(FEATURE_FLAG_TOKENS.FeatureFlagService)\n * private readonly flags: FeatureFlagService\n *\n * const enabled = await this.flags.getBooleanValue('new-checkout')        // manifest default\n * const layout  = await this.flags.use('EXPERIMENT_FLAGS').getStringValue('layout', 'v1')\n * ```\n *\n * @see https://developers.cloudflare.com/flagship/binding/\n */\n@Request(FEATURE_FLAG_TOKENS.FeatureFlagService)\nexport class FeatureFlagService {\n  private readonly apps = new Map<string, FeatureFlagApp>()\n  private bindingName!: string\n  private binding!: Flagship\n  private manifest!: FlagManifest\n\n  constructor(\n    @inject(FEATURE_FLAG_TOKENS.Options) private readonly options: FeatureFlagModuleOptions,\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(ROUTER_TOKENS.RouterContext) private readonly routerContext: RouterContext | null,\n  ) {\n    for (const app of options.apps) {\n      this.apps.set(app.binding, app)\n    }\n    this.bindTo(options.default ?? options.apps[0]?.binding)\n  }\n\n  /**\n   * Switch to a different configured Flagship app.\n   *\n   * Returns a new immutable instance bound to `binding`; the original is\n   * unchanged. The binding must be declared in the module's `apps`.\n   */\n  use(binding: FlagshipBindingName): FeatureFlagService {\n    if (binding === this.bindingName) return this\n    const instance = new FeatureFlagService(this.options, this.env, this.routerContext)\n    instance.bindTo(binding)\n    return instance\n  }\n\n  /** The binding name this instance currently targets. */\n  get app(): string {\n    return this.bindingName\n  }\n\n  // ==================== EVALUATION ====================\n\n  /** Returns the raw flag value without type checking. */\n  async get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown> {\n    return this.binding.get(flagKey, this.fallback(flagKey, defaultValue), await this.context(context))\n  }\n\n  /** Returns the flag value as a `boolean`. */\n  async getBooleanValue(flagKey: string, defaultValue?: boolean, context?: FlagshipEvaluationContext): Promise<boolean> {\n    return this.binding.getBooleanValue(flagKey, this.fallback(flagKey, defaultValue, false), await this.context(context))\n  }\n\n  /** Returns the flag value as a `string`. */\n  async getStringValue(flagKey: string, defaultValue?: string, context?: FlagshipEvaluationContext): Promise<string> {\n    return this.binding.getStringValue(flagKey, this.fallback(flagKey, defaultValue, ''), await this.context(context))\n  }\n\n  /** Returns the flag value as a `number`. */\n  async getNumberValue(flagKey: string, defaultValue?: number, context?: FlagshipEvaluationContext): Promise<number> {\n    return this.binding.getNumberValue(flagKey, this.fallback(flagKey, defaultValue, 0), await this.context(context))\n  }\n\n  /** Returns the flag value as a typed object. */\n  async getObjectValue<T extends object>(flagKey: string, defaultValue?: T, context?: FlagshipEvaluationContext): Promise<T> {\n    return this.binding.getObjectValue<T>(flagKey, this.fallback(flagKey, defaultValue, {} as T), await this.context(context))\n  }\n\n  /** Returns the `boolean` flag value with evaluation metadata. */\n  async getBooleanDetails(flagKey: string, defaultValue?: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>> {\n    return this.binding.getBooleanDetails(flagKey, this.fallback(flagKey, defaultValue, false), await this.context(context))\n  }\n\n  /** Returns the `string` flag value with evaluation metadata. */\n  async getStringDetails(flagKey: string, defaultValue?: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>> {\n    return this.binding.getStringDetails(flagKey, this.fallback(flagKey, defaultValue, ''), await this.context(context))\n  }\n\n  /** Returns the `number` flag value with evaluation metadata. */\n  async getNumberDetails(flagKey: string, defaultValue?: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>> {\n    return this.binding.getNumberDetails(flagKey, this.fallback(flagKey, defaultValue, 0), await this.context(context))\n  }\n\n  /** Returns the typed object flag value with evaluation metadata. */\n  async getObjectDetails<T extends object>(flagKey: string, defaultValue?: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>> {\n    return this.binding.getObjectDetails<T>(flagKey, this.fallback(flagKey, defaultValue, {} as T), await this.context(context))\n  }\n\n  /**\n   * Evaluates every flag declared in the current app's manifest and returns a\n   * `{ key: value }` map. The evaluation method is chosen from each declared\n   * default's type. Powers the Inertia auto-share.\n   */\n  async all(context?: FlagshipEvaluationContext): Promise<Record<string, FlagValue>> {\n    const merged = await this.context(context)\n    const keys = Object.keys(this.manifest)\n    const values = await Promise.all(keys.map((key) => this.evaluate(key, this.manifest[key], merged)))\n    const result: Record<string, FlagValue> = {}\n    keys.forEach((key, i) => {\n      result[key] = values[i]\n    })\n    return result\n  }\n\n  // ==================== INTERNAL ====================\n\n  private bindTo(name: string | undefined): void {\n    if (!name) {\n      throw new FeatureFlagError('No feature flag apps configured. Provide at least one app in FeatureFlagModule.forRoot({ apps: [...] }).')\n    }\n    const app = this.apps.get(name)\n    if (!app) {\n      throw new FeatureFlagError(`Feature flag app \"${name}\" is not configured.`)\n    }\n    const binding = (this.env as unknown as Record<string, unknown>)[name] as Flagship | undefined\n    if (!binding) {\n      throw new FeatureFlagError(`Flagship binding \"${name}\" was not found in the environment.`)\n    }\n    this.bindingName = name\n    this.binding = binding\n    this.manifest = app.flags ?? {}\n  }\n\n  /** Resolves the merged evaluation context (default context + per-call override). */\n  private async context(callContext?: FlagshipEvaluationContext): Promise<FlagshipEvaluationContext | undefined> {\n    if (!this.options.context || !this.routerContext) return callContext\n    const base = await this.options.context(this.routerContext)\n    return callContext ? { ...base, ...callContext } : base\n  }\n\n  /** Picks the default: explicit arg, then manifest, then the type's zero value. */\n  private fallback<T>(flagKey: string, provided: T | undefined, zero?: T): T {\n    if (provided !== undefined) return provided\n    if (flagKey in this.manifest) return this.manifest[flagKey] as T\n    return zero as T\n  }\n\n  /** Evaluates a single flag, choosing the method from the declared default's type. */\n  private evaluate(flagKey: string, declared: FlagValue, context?: FlagshipEvaluationContext): Promise<FlagValue> {\n    switch (typeof declared) {\n      case 'boolean':\n        return this.binding.getBooleanValue(flagKey, declared, context)\n      case 'number':\n        return this.binding.getNumberValue(flagKey, declared, context)\n      case 'string':\n        return this.binding.getStringValue(flagKey, declared, context)\n      default:\n        return this.binding.getObjectValue(flagKey, declared, context)\n    }\n  }\n}\n","import { Module } from 'stratal/module'\nimport type { AsyncModuleOptions, DynamicModule } from 'stratal/module'\nimport type { RouteConfigurable, Router } from 'stratal/router'\nimport { FeatureFlagShareMiddleware } from './feature-flag-share.middleware'\nimport { FEATURE_FLAG_TOKENS } from './feature-flags.tokens'\nimport { FeatureFlagService } from './services/feature-flag.service'\nimport type { FeatureFlagModuleOptions } from './types'\n\n/**\n * Feature Flag Module\n *\n * Evaluates Cloudflare Flagship feature flags through the native Worker binding.\n * Declare your apps (and the flags you use) once; inject {@link FeatureFlagService}\n * to evaluate them.\n *\n * When `@stratal/inertia` is also present, declared flags are auto-shared to\n * every Inertia page as the `featureFlags` prop (read them with `useFlag` /\n * `useFeatureFlags` from `@stratal/feature-flags/react`) — no extra wiring. In\n * a pure-API worker the auto-share middleware is a no-op.\n *\n * @example\n * ```typescript\n * FeatureFlagModule.forRoot({\n *   apps: [{ binding: 'FLAGS', flags: { 'new-checkout': false } }],\n *   context: (ctx) => ({ userId: ctx.user().id }), // ctx.user() from @stratal/framework\n * })\n *\n * // Or async, from config namespaces:\n * FeatureFlagModule.forRootAsync({\n *   inject: [flagsConfig.KEY],\n *   useFactory: (cfg) => ({ apps: cfg.apps, default: cfg.default }),\n * })\n * ```\n */\n@Module({\n  providers: [\n    { provide: FEATURE_FLAG_TOKENS.FeatureFlagService, useClass: FeatureFlagService },\n  ],\n})\nexport class FeatureFlagModule implements RouteConfigurable {\n  /** Auto-shares declared flags to every Inertia page (no-op without Inertia). */\n  configureRoutes(router: Router): void {\n    router.use(FeatureFlagShareMiddleware)\n  }\n\n  /** Configure with static options. */\n  static forRoot(options: FeatureFlagModuleOptions): DynamicModule {\n    return {\n      module: FeatureFlagModule,\n      providers: [\n        { provide: FEATURE_FLAG_TOKENS.Options, useValue: options },\n      ],\n    }\n  }\n\n  /** Configure with an async factory (when options depend on other services). */\n  static forRootAsync(options: AsyncModuleOptions<FeatureFlagModuleOptions>): DynamicModule {\n    return {\n      module: FeatureFlagModule,\n      providers: [\n        {\n          provide: FEATURE_FLAG_TOKENS.Options,\n          useFactory: options.useFactory,\n          inject: options.inject,\n        },\n      ],\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/react.d.mts

@@ -0,0 +1,24 @@
+import { r as FeatureFlagRegistry } from "./types-Dxuc-7SJ.mjs";
+
+//#region src/react/use-feature-flags.d.ts
+/**
+ * Returns the full map of feature flags shared by `FeatureFlagInertiaModule`.
+ */
+declare function useFeatureFlags(): Record<string, unknown>;
+/**
+ * Returns a single shared feature flag value.
+ *
+ * When you augment {@link FeatureFlagRegistry}, the key and return type are
+ * checked against your declared flags. Otherwise pass an explicit default.
+ *
+ * @example
+ * ```tsx
+ * const showNewCheckout = useFlag('new-checkout')        // typed via FeatureFlagRegistry
+ * const layout = useFlag('layout', 'v1')                 // loose fallback
+ * ```
+ */
+declare function useFlag<K extends keyof FeatureFlagRegistry>(key: K): FeatureFlagRegistry[K];
+declare function useFlag<T>(key: string, defaultValue: T): T;
+//#endregion
+export { useFeatureFlags, useFlag };
+//# sourceMappingURL=react.d.mts.map

package/dist/react.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.mts","names":[],"sources":["../src/react/use-feature-flags.ts"],"mappings":";;;;;AAWA;iBAAgB,eAAA,CAAA,GAAmB,MAAA;;;;AAgBnC;;;;;;;;;iBAAgB,OAAA,iBAAwB,mBAAA,CAAA,CAAqB,GAAA,EAAK,CAAA,GAAI,mBAAA,CAAoB,CAAA;AAAA,iBAC1E,OAAA,GAAA,CAAW,GAAA,UAAa,YAAA,EAAc,CAAA,GAAI,CAAA"}

package/dist/react.mjs

@@ -0,0 +1,16 @@
+import { usePage } from "@inertiajs/react";
+//#region src/react/use-feature-flags.ts
+/**
+* Returns the full map of feature flags shared by `FeatureFlagInertiaModule`.
+*/
+function useFeatureFlags() {
+	return usePage().props.featureFlags ?? {};
+}
+function useFlag(key, defaultValue) {
+	const flags = useFeatureFlags();
+	return key in flags ? flags[key] : defaultValue;
+}
+//#endregion
+export { useFeatureFlags, useFlag };
+
+//# sourceMappingURL=react.mjs.map

package/dist/react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.mjs","names":[],"sources":["../src/react/use-feature-flags.ts"],"sourcesContent":["import type { PageProps } from '@inertiajs/core'\nimport { usePage } from '@inertiajs/react'\nimport type { FeatureFlagRegistry } from '../types'\n\ninterface FeatureFlagsPageProps extends PageProps {\n  featureFlags?: Record<string, unknown>\n}\n\n/**\n * Returns the full map of feature flags shared by `FeatureFlagInertiaModule`.\n */\nexport function useFeatureFlags(): Record<string, unknown> {\n  return usePage<FeatureFlagsPageProps>().props.featureFlags ?? {}\n}\n\n/**\n * Returns a single shared feature flag value.\n *\n * When you augment {@link FeatureFlagRegistry}, the key and return type are\n * checked against your declared flags. Otherwise pass an explicit default.\n *\n * @example\n * ```tsx\n * const showNewCheckout = useFlag('new-checkout')        // typed via FeatureFlagRegistry\n * const layout = useFlag('layout', 'v1')                 // loose fallback\n * ```\n */\nexport function useFlag<K extends keyof FeatureFlagRegistry>(key: K): FeatureFlagRegistry[K]\nexport function useFlag<T>(key: string, defaultValue: T): T\nexport function useFlag(key: string, defaultValue?: unknown): unknown {\n  const flags = useFeatureFlags()\n  return key in flags ? flags[key] : defaultValue\n}\n"],"mappings":";;;;;AAWA,SAAgB,kBAA2C;CACzD,OAAO,SAAgC,CAAC,MAAM,gBAAgB,EAAE;;AAiBlE,SAAgB,QAAQ,KAAa,cAAiC;CACpE,MAAM,QAAQ,iBAAiB;CAC/B,OAAO,OAAO,QAAQ,MAAM,OAAO"}

package/dist/types-Dxuc-7SJ.d.mts

@@ -0,0 +1,71 @@
+import { RouterContext } from "stratal/router";
+import { StratalEnv } from "stratal";
+
+//#region src/types.d.ts
+/**
+ * A value a feature flag can resolve to.
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/methods/
+ */
+type FlagValue = boolean | string | number | object;
+/**
+ * String keys of the augmented `StratalEnv` whose value is a Flagship binding.
+ */
+type FlagshipBindingFromEnv = Extract<{ [K in keyof StratalEnv]: StratalEnv[K] extends Flagship ? K : never }[keyof StratalEnv], string>;
+/**
+ * Type-safe Flagship binding name.
+ *
+ * Resolves to the union of `Flagship`-typed binding keys on the augmented
+ * `StratalEnv`. Falls back to `string` when no Flagship bindings are visible
+ * (for example library code compiled outside an app's env context).
+ */
+type FlagshipBindingName = [FlagshipBindingFromEnv] extends [never] ? string : FlagshipBindingFromEnv;
+/**
+ * Augment this interface to get typed flag keys for `useFlag()` and the service.
+ *
+ * @example
+ * ```typescript
+ * declare module '@stratal/feature-flags' {
+ *   interface FeatureFlagRegistry {
+ *     'new-checkout': boolean
+ *     'checkout-flow': string
+ *   }
+ * }
+ * ```
+ */
+interface FeatureFlagRegistry {}
+/**
+ * A declared set of flags and their default values.
+ *
+ * Flagship has no enumeration API, so the flags you intend to evaluate (and
+ * auto-share to the frontend) must be declared once here. The default also
+ * doubles as the type hint used to pick the evaluation method in `all()`.
+ */
+type FlagManifest = Record<string, FlagValue>;
+/**
+ * A single Flagship app bound to the Worker.
+ */
+interface FeatureFlagApp {
+  /** Flagship binding name from your Wrangler config (type-checked against `StratalEnv`). */
+  binding: FlagshipBindingName;
+  /** Declared flags + defaults for this app. Used for manifest defaults and Inertia auto-share. */
+  flags?: FlagManifest;
+}
+/**
+ * Feature-flags module configuration.
+ */
+interface FeatureFlagModuleOptions {
+  /** One or more Flagship apps. A Worker may bind to multiple apps. */
+  apps: FeatureFlagApp[];
+  /** Default app binding used by the injected `FeatureFlagService`. Defaults to `apps[0].binding`. */
+  default?: FlagshipBindingName;
+  /**
+   * Resolves a per-request evaluation context (for example `{ userId }`) merged
+   * into every evaluation. Per-call context passed to a method overrides these.
+   * Receives the current request context; skipped outside request scope.
+   */
+  context?: (ctx: RouterContext) => FlagshipEvaluationContext | Promise<FlagshipEvaluationContext>;
+}
+//#endregion
+export { FlagValue as a, FlagManifest as i, FeatureFlagModuleOptions as n, FlagshipBindingName as o, FeatureFlagRegistry as r, FeatureFlagApp as t };
+//# sourceMappingURL=types-Dxuc-7SJ.d.mts.map

package/dist/types-Dxuc-7SJ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Dxuc-7SJ.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;AAQA;;;KAAY,SAAA;;AAA8C;;KAKrD,sBAAA,GAAyB,OAAA,eACd,UAAA,GAAa,UAAA,CAAW,CAAA,UAAW,QAAA,GAAW,CAAA,iBAAkB,UAAA;;;;;;;;KAWpE,mBAAA,IAAuB,sBAAA,6BAE/B,sBAAA;;;;;;;;;;AAFJ;;;;UAiBiB,mBAAA;;;;;AASjB;;;KAAY,YAAA,GAAe,MAAA,SAAe,SAAA;;AAK1C;;UAAiB,cAAA;EAIK;EAFpB,OAAA,EAAS,mBAAA;EAAA;EAET,KAAA,GAAQ,YAAA;AAAA;;;AAMV;UAAiB,wBAAA;;EAEf,IAAA,EAAM,cAAA;EAEI;EAAV,OAAA,GAAU,mBAAA;EAMwB;;;;;EAAlC,OAAA,IAAW,GAAA,EAAK,aAAA,KAAkB,yBAAA,GAA4B,OAAA,CAAQ,yBAAA;AAAA"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@stratal/feature-flags",
+  "version": "0.0.21",
+  "description": "Cloudflare Flagship feature flags for the Stratal framework — binding API wrapper with Inertia.js auto-sharing",
+  "type": "module",
+  "license": "MIT",
+  "author": "Temitayo Fadojutimi",
+  "homepage": "https://github.com/strataljs/stratal#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strataljs/stratal.git",
+    "directory": "packages/feature-flags"
+  },
+  "bugs": {
+    "url": "https://github.com/strataljs/stratal/issues"
+  },
+  "keywords": [
+    "stratal",
+    "feature-flags",
+    "flagship",
+    "cloudflare-workers",
+    "inertia",
+    "react"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.mts",
+      "import": "./dist/react.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "npx oxlint .",
+    "lint:fix": "npx oxlint --fix ."
+  },
+  "peerDependencies": {
+    "@inertiajs/react": ">=3",
+    "@stratal/inertia": ">=0.0.21",
+    "hono": ">=4",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "stratal": ">=0.0.21"
+  },
+  "peerDependenciesMeta": {
+    "@inertiajs/react": {
+      "optional": true
+    },
+    "@stratal/inertia": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "4.20260528.1",
+    "@inertiajs/core": "^3.1.1",
+    "@inertiajs/react": "^3.1.1",
+    "@types/node": "^25.6.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "hono": "^4.12.18",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "stratal": "workspace:*",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "vitest": "~4.1.5"
+  }
+}