@cfast/core 0.1.2 → 0.1.4

package/README.md

@@ -130,7 +130,7 @@ import { app } from '~/cfast';
 
 export async function loader({ request, context }: Route.LoaderArgs) {
   const ctx = await app.context(request, context);
-  return ctx.db.client.query(posts).findMany().run({});
+  return ctx.db.client.query(posts).findMany().run();
 }
 ```
 
@@ -165,7 +165,7 @@ Optional convenience wrappers that call `app.context()` and pass the result as t
 
 ```typescript
 export const loader = app.loader(async (ctx, { params }) => {
-  return ctx.db.client.query(posts).findMany().run({});
+  return ctx.db.client.query(posts).findMany().run();
 });
 ```
 
@@ -443,7 +443,7 @@ export async function loader({ request, context }: Route.LoaderArgs) {
   }
   await ctx['rate-limit'].consume();
 
-  return ctx.db.client.query(posts).findMany().run({});
+  return ctx.db.client.query(posts).findMany().run();
 }
 ```
 

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { e as RuntimePlugin } from '../types-C2gJHKfQ.js';
+import { f as RuntimePlugin } from '../types-CQyKq4D1.js';
 import '@cfast/env';
 import '@cfast/permissions';
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Schema } from '@cfast/env';
 import { Permissions } from '@cfast/permissions';
-import { C as CreateAppConfig, A as App, a as CfastPlugin, P as PluginSetupContext, R as RequiresFromPlugins } from './types-C2gJHKfQ.js';
-export { b as AppContext, c as PluginProvides, d as RouteArgs } from './types-C2gJHKfQ.js';
+import { C as CreateAppConfig, A as App, a as CfastPlugin, P as PluginSetupContext, R as RequiresFromPlugins } from './types-CQyKq4D1.js';
+export { b as AppContext, c as PluginContext, d as PluginProvides, e as RouteArgs } from './types-CQyKq4D1.js';
 import { ComponentType, ReactNode } from 'react';
 
 /**
@@ -90,7 +90,7 @@ declare function createApp<TSchema extends Schema, TPermissions extends Permissi
  * });
  * ```
  */
-declare function definePlugin<TName extends string, TProvides, const TRequires extends readonly CfastPlugin<string, unknown, any, unknown>[] = [], TClient = unknown>(config: {
+declare function definePlugin<TName extends string, TProvides, const TRequires extends readonly CfastPlugin<string, unknown, any, unknown, any>[] = [], TClient = unknown>(config: {
     name: TName;
     requires?: TRequires;
     setup: (ctx: PluginSetupContext<RequiresFromPlugins<TRequires>>) => TProvides | Promise<TProvides>;
@@ -107,6 +107,53 @@ declare function definePlugin<TRequires>(): <TName extends string, TProvides, TC
     }>;
     client?: TClient;
 }) => CfastPlugin<TName, Awaited<TProvides>, TRequires, TClient>;
+/**
+ * Returns an env-typed `definePlugin` factory.
+ *
+ * The scaffolded `Cloudflare.Env` type from `worker-configuration.d.ts` is
+ * not known to `@cfast/core` at build time, so the generic `definePlugin`
+ * exposes `ctx.env` as the loose `Record<string, unknown>` shape and
+ * consumers have to cast bindings (e.g. `ctx.env.DB as D1Database`). Apps
+ * that want precise bindings call this factory once with their env type
+ * and re-export the typed `definePlugin` from a local module:
+ *
+ * ```ts
+ * // app/plugins/define-plugin.ts
+ * import { definePluginFor } from "@cfast/core";
+ *
+ * export const definePlugin = definePluginFor<Cloudflare.Env>();
+ * ```
+ *
+ * Plugin authors then import from their local module and get `ctx.env.DB`
+ * typed as `D1Database` without any casting:
+ *
+ * ```ts
+ * import { definePlugin } from "~/plugins/define-plugin";
+ *
+ * export const dbPlugin = definePlugin({
+ *   name: "db",
+ *   setup(ctx) {
+ *     const db = ctx.env.DB; // D1Database, no cast
+ *     return { client: createDb({ d1: db }) };
+ *   },
+ * });
+ * ```
+ *
+ * The returned factory has the same shape as {@link definePlugin} (with the
+ * curried legacy overload preserved) so existing code that switches from the
+ * generic form to the env-typed form only needs an import swap.
+ */
+declare function definePluginFor<TEnv>(): {
+    <TName extends string, TProvides, const TRequires extends readonly CfastPlugin<string, unknown, any, unknown, any>[] = [], TClient = unknown>(config: {
+        name: TName;
+        requires?: TRequires;
+        setup: (ctx: PluginSetupContext<RequiresFromPlugins<TRequires>, TEnv>) => TProvides | Promise<TProvides>;
+        Provider?: ComponentType<{
+            children: ReactNode;
+        }>;
+        client?: TClient;
+    }): CfastPlugin<TName, Awaited<TProvides>, RequiresFromPlugins<TRequires>, TClient, TEnv>;
+};
 
 /**
  * Error thrown when a plugin's `setup()` function fails during `app.context()`.
@@ -134,4 +181,4 @@ declare class CfastConfigError extends Error {
     constructor(message: string);
 }
 
-export { App, CfastConfigError, CfastPlugin, CfastPluginError, CreateAppConfig, PluginSetupContext, createApp, definePlugin };
+export { App, CfastConfigError, CfastPlugin, CfastPluginError, CreateAppConfig, PluginSetupContext, createApp, definePlugin, definePluginFor };

package/dist/index.js

@@ -114,9 +114,13 @@ function definePlugin(config) {
   }
   return config;
 }
+function definePluginFor() {
+  return (config) => config;
+}
 export {
   CfastConfigError,
   CfastPluginError,
   createApp,
-  definePlugin
+  definePlugin,
+  definePluginFor
 };

package/dist/{types-C2gJHKfQ.d.ts → types-CQyKq4D1.d.ts}

@@ -20,14 +20,43 @@ type CreateAppConfig<TSchema extends Schema, TPermissions extends Permissions> =
  * Contains the current request, validated env, and all values provided by prior plugins
  * (typed via `TRequires`).
  *
+ * By default `env` is typed as the loose `Record<string, unknown>` shape used
+ * by the framework's generic plugin layer. Consumer apps that want precise
+ * bindings (e.g. `Cloudflare.Env` from `worker-configuration.d.ts`) can
+ * specialise the type via {@link definePluginFor} or by importing the
+ * {@link PluginContext} helper directly.
+ *
  * @typeParam TRequires - Intersection of prior plugin provides (e.g., `AuthPluginProvides`).
+ * @typeParam TEnv - Env shape (defaults to the loose record shape).
  */
-type PluginSetupContext<TRequires> = {
+type PluginSetupContext<TRequires, TEnv = Record<string, unknown>> = {
     /** The incoming HTTP request for the current invocation. */
     request: Request;
     /** The validated environment bindings. */
-    env: Record<string, unknown>;
+    env: TEnv;
 } & TRequires;
+/**
+ * Convenience alias for consumers who want to annotate a plugin's `setup(ctx)`
+ * parameter without going through {@link definePluginFor}. Re-exported from
+ * the package entry as `PluginContext`.
+ *
+ * @example
+ * ```ts
+ * import type { PluginContext } from "@cfast/core";
+ * import type { PluginProvides } from "@cfast/core";
+ * import type { authPlugin } from "./plugins/auth";
+ *
+ * export const dbPlugin = definePlugin({
+ *   name: "db",
+ *   requires: [authPlugin],
+ *   setup(ctx: PluginContext<Cloudflare.Env, PluginProvides<typeof authPlugin>>) {
+ *     const db = ctx.env.DB; // typed as D1Database, no cast
+ *     return { client: createDb({ d1: db }) };
+ *   },
+ * });
+ * ```
+ */
+type PluginContext<TEnv = Record<string, unknown>, TRequires = unknown> = PluginSetupContext<TRequires, TEnv>;
 /**
  * A cfast plugin definition created by {@link definePlugin}.
  *
@@ -38,8 +67,10 @@ type PluginSetupContext<TRequires> = {
  * @typeParam TProvides - The type returned by `setup()`, accessible as `ctx[name]`.
  * @typeParam TRequires - The context shape this plugin depends on from prior plugins.
  * @typeParam TClient - Client-side values exposed via `useApp()`.
+ * @typeParam TEnv - Env shape seen by `setup()`. Defaults to the loose record
+ *   shape so non-specialised plugins do not need to parameterise this slot.
  */
-type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires = unknown, TClient = unknown> = {
+type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires = unknown, TClient = unknown, TEnv = Record<string, unknown>> = {
     /** Unique identifier used as the namespace key in the app context. */
     name: TName;
     /**
@@ -49,9 +80,9 @@ type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires =
      * required plugin's provides, and `app.use(this)` will throw at registration
      * time if any of these plugins have not yet been registered.
      */
-    requires?: readonly CfastPlugin<string, unknown, any, unknown>[];
+    requires?: readonly CfastPlugin<string, unknown, any, unknown, any>[];
     /** Called per-request to produce the values this plugin provides. */
-    setup: (ctx: PluginSetupContext<TRequires>) => TProvides | Promise<TProvides>;
+    setup: (ctx: PluginSetupContext<TRequires, TEnv>) => TProvides | Promise<TProvides>;
     /** Optional client-side React provider, composed into `app.Provider`. */
     Provider?: ComponentType<{
         children: ReactNode;
@@ -80,8 +111,8 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
  * required plugins each contribute their own `{ name: provides }` shape rather
  * than collapsing into a union of widened `provides` values.
  */
-type RequiresFromPlugins<R extends readonly CfastPlugin<string, unknown, any, unknown>[]> = R extends readonly [] ? unknown : UnionToIntersection<{
-    [K in keyof R]: R[K] extends CfastPlugin<infer N, infer P, unknown, unknown> ? {
+type RequiresFromPlugins<R extends readonly CfastPlugin<string, unknown, any, unknown, any>[]> = R extends readonly [] ? unknown : UnionToIntersection<{
+    [K in keyof R]: R[K] extends CfastPlugin<infer N, infer P, unknown, unknown, any> ? {
         [Key in N]: P;
     } : never;
 }[number]>;
@@ -108,7 +139,7 @@ type RuntimePlugin = {
      * `app.use(plugin)` walks this list and verifies each entry is already
      * registered, throwing `CfastConfigError` immediately if not.
      */
-    requires?: readonly CfastPlugin<string, unknown, any, unknown>[];
+    requires?: readonly CfastPlugin<string, unknown, any, unknown, any>[];
     /**
      * Setup function called per-request.
      *
@@ -130,7 +161,7 @@ type RuntimePlugin = {
  *
  * @typeParam T - A `CfastPlugin` type to extract provides from.
  */
-type PluginProvides<T> = T extends CfastPlugin<infer N, infer P, unknown, unknown> ? {
+type PluginProvides<T> = T extends CfastPlugin<infer N, infer P, unknown, unknown, any> ? {
     [K in N]: P;
 } : never;
 /**
@@ -179,7 +210,7 @@ type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContex
     /** Convenience wrapper for React Router actions that auto-creates the app context. */
     action<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
     /** Registers a plugin, extending the app's context type. Throws on duplicate names. */
-    use<TName extends string, TProvides, TClient>(plugin: CfastPlugin<TName, TProvides, TPluginContext, TClient>): App<TSchema, TPermissions, TPluginContext & {
+    use<TName extends string, TProvides, TClient, TEnv = any>(plugin: CfastPlugin<TName, TProvides, TPluginContext, TClient, TEnv>): App<TSchema, TPermissions, TPluginContext & {
         [K in TName]: TProvides;
     }, TClientContext & (TClient extends object ? {
         [K in TName]: TClient;
@@ -192,4 +223,4 @@ type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContex
     permissions: TPermissions;
 };
 
-export type { App as A, CreateAppConfig as C, PluginSetupContext as P, RequiresFromPlugins as R, CfastPlugin as a, AppContext as b, PluginProvides as c, RouteArgs as d, RuntimePlugin as e };
+export type { App as A, CreateAppConfig as C, PluginSetupContext as P, RequiresFromPlugins as R, CfastPlugin as a, AppContext as b, PluginContext as c, PluginProvides as d, RouteArgs as e, RuntimePlugin as f };

package/llms.txt

@@ -106,6 +106,38 @@ definePlugin<AuthPluginProvides>()({
 Prefer the inferred form (`requires: [authPlugin]`) when you can — it removes
 the need to declare and import a `PluginProvides` type token.
 
+### Typed env (`definePluginFor<Env>`)
+
+The generic `definePlugin` exposes `ctx.env` as `Record<string, unknown>`
+because `@cfast/core` cannot know your scaffolded `Cloudflare.Env` shape. To
+avoid `ctx.env.DB as D1Database` casts in every plugin, call `definePluginFor`
+once with your env type and re-export the typed factory from a local module:
+
+```typescript
+// app/plugins/define-plugin.ts
+import { definePluginFor } from "@cfast/core";
+export const definePlugin = definePluginFor<Cloudflare.Env>();
+```
+
+```typescript
+// app/plugins/db.ts
+import { definePlugin } from "~/plugins/define-plugin";
+
+export const dbPlugin = definePlugin({
+  name: "db",
+  requires: [authPlugin],
+  setup(ctx) {
+    const db = ctx.env.DB; // typed as D1Database — no cast
+    return { client: createDb({ d1: db, /* ... */ }) };
+  },
+});
+```
+
+The returned factory has the same shape as `definePlugin`, so plugins built
+with it slot into existing `app.use()` calls without further changes. If you
+prefer to type a single plugin in-place without a factory, import the
+`PluginContext<Env, TRequires>` helper and annotate the parameter directly.
+
 ### Client (`@cfast/core/client`)
 
 ```typescript
@@ -158,12 +190,12 @@ export default {
 // Using app.context() directly:
 export async function loader({ request, context }: Route.LoaderArgs) {
   const ctx = await app.context(request, context);
-  return ctx.db.client.query(posts).findMany().run({});
+  return ctx.db.client.query(posts).findMany().run();
 }
 
 // Using convenience wrapper:
 export const loader = app.loader(async (ctx, { params }) => {
-  return ctx.db.client.query(posts).findMany().run({});
+  return ctx.db.client.query(posts).findMany().run();
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "App composition layer with plugin system for @cfast/* packages",
   "keywords": [
     "cfast",
@@ -36,14 +36,18 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@cfast/permissions": "0.2.0",
-    "@cfast/env": "0.1.1"
-  },
   "peerDependencies": {
+    "@cfast/env": ">=0.1.0 <0.3.0",
+    "@cfast/permissions": ">=0.3.0 <0.6.0",
     "react": ">=18"
   },
   "peerDependenciesMeta": {
+    "@cfast/env": {
+      "optional": false
+    },
+    "@cfast/permissions": {
+      "optional": false
+    },
     "react": {
       "optional": true
     }
@@ -55,7 +59,9 @@
     "react-dom": "^19.2.4",
     "tsup": "^8",
     "typescript": "^5.7",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@cfast/permissions": "0.5.1",
+    "@cfast/env": "0.2.1"
   },
   "scripts": {
     "build": "tsup src/index.ts src/client/index.ts --format esm --dts",