@cfast/core 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { d as RuntimePlugin } from '../types-L3fwnDhg.js';
+import { e as RuntimePlugin } from '../types-C2gJHKfQ.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, P as PluginSetupContext, a as CfastPlugin } from './types-L3fwnDhg.js';
-export { b as AppContext, c as PluginProvides, R as RouteArgs } from './types-L3fwnDhg.js';
+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 { ComponentType, ReactNode } from 'react';
 
 /**
@@ -29,12 +29,44 @@ declare function createApp<TSchema extends Schema, TPermissions extends Permissi
 /**
  * Defines a cfast plugin for use with `createApp().use()`.
  *
- * Has two call signatures:
- * - **Direct form** (no dependencies): `definePlugin({ name, setup, ... })` -- types are fully inferred.
- * - **Curried form** (with dependencies): `definePlugin<TRequires>()({ name, setup, ... })` --
- *   specify `TRequires` explicitly so `setup(ctx)` receives typed prior-plugin context.
+ * Two equivalent forms are supported:
  *
- * @param config - Plugin configuration with `name`, `setup`, and optional `Provider`/`client`.
+ * 1. **Inferred form (preferred)** — pass plugin references in `requires` and the
+ *    `setup(ctx)` parameter is automatically typed with their provides:
+ *
+ *    ```ts
+ *    const dbPlugin = definePlugin({
+ *      name: "db",
+ *      requires: [authPlugin],
+ *      setup(ctx) {
+ *        ctx.auth.user; // typed from authPlugin
+ *        return { client: createDb({}) };
+ *      },
+ *    });
+ *    ```
+ *
+ *    No need to import or declare a `TRequires` type token — the dependency type
+ *    flows directly from the registered plugin objects. Leaf plugins simply omit
+ *    `requires` and get `ctx: { request, env }`.
+ *
+ * 2. **Curried form (legacy)** — kept for backward compatibility with code that
+ *    only has access to a `PluginProvides<typeof authPlugin>` *type* (e.g. when
+ *    you cannot import the actual plugin value):
+ *
+ *    ```ts
+ *    definePlugin<AuthPluginProvides>()({
+ *      name: "db",
+ *      setup(ctx) { ctx.auth.user; return { ... }; },
+ *    });
+ *    ```
+ *
+ * Plugins declared via the inferred form also benefit from runtime validation:
+ * `app.use(plugin)` throws a `CfastConfigError` if any plugin listed in
+ * `requires` has not yet been registered, with a message that names the missing
+ * dependency.
+ *
+ * @param config - Plugin configuration with `name`, `setup`, and optional
+ *                 `requires`, `Provider`, `client`.
  * @returns A `CfastPlugin` instance ready to pass to `app.use()`.
  *
  * @example
@@ -47,25 +79,26 @@ declare function createApp<TSchema extends Schema, TPermissions extends Permissi
  *   },
  * });
  *
- * // Plugin with dependencies (curried)
- * import type { AuthPluginProvides } from '@cfast/auth';
- * const dbPlugin = definePlugin<AuthPluginProvides>()({
+ * // Dependent plugin — requires inferred from plugin references
+ * const dbPlugin = definePlugin({
  *   name: 'db',
+ *   requires: [authPlugin],
  *   setup(ctx) {
- *     ctx.auth.user; // typed from AuthPluginProvides
+ *     ctx.auth.user; // typed from authPlugin
  *     return { client: createDb({}) };
  *   },
  * });
  * ```
  */
-declare function definePlugin<TName extends string, TProvides, TClient = unknown>(config: {
+declare function definePlugin<TName extends string, TProvides, const TRequires extends readonly CfastPlugin<string, unknown, any, unknown>[] = [], TClient = unknown>(config: {
     name: TName;
-    setup: (ctx: PluginSetupContext<unknown>) => TProvides | Promise<TProvides>;
+    requires?: TRequires;
+    setup: (ctx: PluginSetupContext<RequiresFromPlugins<TRequires>>) => TProvides | Promise<TProvides>;
     Provider?: ComponentType<{
         children: ReactNode;
     }>;
     client?: TClient;
-}): CfastPlugin<TName, Awaited<TProvides>, unknown, TClient>;
+}): CfastPlugin<TName, Awaited<TProvides>, RequiresFromPlugins<TRequires>, TClient>;
 declare function definePlugin<TRequires>(): <TName extends string, TProvides, TClient = unknown>(config: {
     name: TName;
     setup: (ctx: PluginSetupContext<TRequires>) => TProvides | Promise<TProvides>;

package/dist/index.js

@@ -91,6 +91,15 @@ function buildApp(envInstance, permissions, plugins) {
           `Duplicate plugin name "${plugin.name}". Each plugin must have a unique name.`
         );
       }
+      if (plugin.requires) {
+        for (const dep of plugin.requires) {
+          if (!pluginNames.has(dep.name)) {
+            throw new CfastConfigError(
+              `Plugin "${plugin.name}" requires "${dep.name}" but it has not been registered. Did you call .use(${dep.name}Plugin) before .use(${plugin.name}Plugin)?`
+            );
+          }
+        }
+      }
       return buildApp(envInstance, permissions, [...plugins, plugin]);
     },
     Provider: createCoreProvider(plugins)

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

@@ -42,6 +42,14 @@ type PluginSetupContext<TRequires> = {
 type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires = unknown, TClient = unknown> = {
     /** Unique identifier used as the namespace key in the app context. */
     name: TName;
+    /**
+     * Optional list of plugin references this plugin depends on.
+     *
+     * When supplied, `setup(ctx)` is automatically typed with the union of each
+     * 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>[];
     /** Called per-request to produce the values this plugin provides. */
     setup: (ctx: PluginSetupContext<TRequires>) => TProvides | Promise<TProvides>;
     /** Optional client-side React provider, composed into `app.Provider`. */
@@ -51,6 +59,32 @@ type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires =
     /** Optional client-side values exposed via `useApp()`. */
     client?: TClient;
 };
+/**
+ * Converts a union type to an intersection type.
+ *
+ * Used by {@link RequiresFromPlugins} to merge each required plugin's provides
+ * into a single intersection that becomes the `setup(ctx)` parameter shape.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Derives the `TRequires` shape for a `setup(ctx)` parameter from an array of
+ * plugin references passed via `definePlugin({ requires: [...] })`.
+ *
+ * Each plugin in the tuple contributes `{ [name]: provides }` and the results
+ * are intersected so `ctx` exposes every required plugin's namespace at the
+ * right key. An empty `requires` tuple resolves to `unknown` (no extra fields).
+ *
+ * Implementation note: we walk the tuple positionally with a mapped type
+ * (`{ [K in keyof R]: ... }[number]`) instead of using `R[number]` directly.
+ * The mapped form preserves per-element inference of `N` and `P`, so multiple
+ * 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> ? {
+        [Key in N]: P;
+    } : never;
+}[number]>;
 /**
  * Minimal plugin shape used internally for runtime iteration in `buildApp`.
  *
@@ -68,6 +102,13 @@ type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires =
 type RuntimePlugin = {
     /** Plugin name used as the namespace key. */
     name: string;
+    /**
+     * Optional dependencies declared via `definePlugin({ requires: [...] })`.
+     *
+     * `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>[];
     /**
      * Setup function called per-request.
      *
@@ -151,4 +192,4 @@ type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContex
     permissions: TPermissions;
 };
 
-export type { App as A, CreateAppConfig as C, PluginSetupContext as P, RouteArgs as R, CfastPlugin as a, AppContext as b, PluginProvides as c, RuntimePlugin as d };
+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 };

package/llms.txt

@@ -10,7 +10,7 @@ Use `@cfast/core` when you want multiple cfast packages (auth, db, storage, etc.
 
 - **Plugin chain**: Plugins run in registration order via `.use()`. Each plugin's `setup()` receives everything prior plugins provided, plus `request` and `env`.
 - **Namespaced context**: Each plugin's return value is nested under its `name` key (e.g., `ctx.auth.user`, `ctx.db.client`). No flat merging, no collisions.
-- **Compile-time dependencies**: Dependent plugins declare requirements via `definePlugin<TRequires>()` (curried form). TypeScript catches missing dependencies at the `.use()` call site.
+- **Inferred dependencies**: Dependent plugins list their requirements as plugin references in `requires: [authPlugin]`. TypeScript infers `setup(ctx)` from the listed plugins -- no manual `TRequires` type token needed. TypeScript also catches missing dependencies at the `.use()` call site, and `app.use(plugin)` throws a clear `CfastConfigError` at runtime if a required plugin has not yet been registered.
 - **Client provider composition**: `<app.Provider>` nests all plugin React providers in registration order. `useApp()` accesses client-side plugin exports.
 
 ## API Reference
@@ -37,7 +37,7 @@ app.permissions: TPermissions                           // permissions config
 ### Plugin definition
 
 ```typescript
-// Leaf plugin (no dependencies) -- direct form, full inference
+// Leaf plugin (no dependencies) -- types are fully inferred
 definePlugin({
   name: "analytics",
   setup(ctx) { return { track: (event: string) => {} }; },
@@ -45,27 +45,67 @@ definePlugin({
   client?: { /* client-side values for useApp() */ },
 }): CfastPlugin
 
-// Dependent plugin -- curried form, specify TRequires explicitly
-definePlugin<AuthPluginProvides>()({
+// Dependent plugin -- list plugin references in `requires`. The setup ctx is
+// inferred from those plugins automatically; no manual generic, no type token.
+const authPlugin = definePlugin({
+  name: "auth",
+  setup() { return { user: getUser(), grants: getGrants() }; },
+});
+
+const dbPlugin = definePlugin({
   name: "db",
+  requires: [authPlugin],
   setup(ctx) {
-    ctx.auth.user;  // typed from AuthPluginProvides
-    return { client: createDb({}) };
+    ctx.auth.user;   // typed from authPlugin
+    ctx.auth.grants; // typed from authPlugin
+    return { client: createDb({ grants: ctx.auth.grants }) };
   },
 }): CfastPlugin
+
+// Multiple dependencies -- list each one
+const adminPlugin = definePlugin({
+  name: "admin",
+  requires: [authPlugin, dbPlugin],
+  setup(ctx) {
+    ctx.auth.user;   // typed
+    ctx.db.client;   // typed
+    return { /* ... */ };
+  },
+});
+```
+
+### Runtime dependency validation
+
+`app.use(plugin)` throws `CfastConfigError` immediately if a plugin listed in
+`requires` has not yet been registered:
+
+```
+CfastConfigError: Plugin "db" requires "auth" but it has not been registered.
+Did you call .use(authPlugin) before .use(dbPlugin)?
 ```
 
-### Plugin type token
+This catches misordering at composition time instead of letting it surface as
+an undefined access deep in the request lifecycle.
+
+### Plugin type token (legacy curried form)
+
+For situations where you only have access to a *type*, not the actual plugin
+value (e.g. you cannot import the plugin module), the legacy curried form is
+still available:
 
 ```typescript
-// Each package exports a type token for dependents:
 export type AuthPluginProvides = PluginProvides<typeof authPlugin>;
 // Resolves to: { auth: { user: AuthUser | null; grants: Grant[]; instance: AuthInstance } }
 
-// Multiple dependencies -- intersect type tokens:
-definePlugin<AuthPluginProvides & DbPluginProvides>()({ ... })
+definePlugin<AuthPluginProvides>()({
+  name: "db",
+  setup(ctx) { ctx.auth.user; return { /* ... */ }; },
+});
 ```
 
+Prefer the inferred form (`requires: [authPlugin]`) when you can — it removes
+the need to declare and import a `PluginProvides` type token.
+
 ### Client (`@cfast/core/client`)
 
 ```typescript
@@ -160,8 +200,13 @@ export const { createAction, composeActions } = createActions({
 
 ## Common Mistakes
 
-- Registering plugins in the wrong order -- `dbPlugin` depends on `authPlugin`, so auth must be `.use()`'d first. TypeScript catches this at compile time.
+- Registering plugins in the wrong order -- `dbPlugin` depends on `authPlugin`, so auth must be `.use()`'d first. TypeScript catches this at compile time, and `.use()` also throws `CfastConfigError` immediately at runtime if a plugin's `requires` are unsatisfied.
 - Calling `app.context()` before `app.init()` -- env is not validated yet, will throw.
 - Calling `useApp()` outside `<app.Provider>` -- throws a context error.
 - Registering two plugins with the same `name` -- throws `CfastConfigError` at import time.
 - Doing expensive work in `setup()` -- it runs on every request. Move one-time init to the plugin factory (outer function).
+
+## See Also
+
+- `@cfast/env` -- Type-safe Cloudflare bindings validated by `app.init()`.
+- `@cfast/permissions` -- Grants resolved per-request and exposed via `app.context()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "App composition layer with plugin system for @cfast/* packages",
   "keywords": [
     "cfast",
@@ -36,16 +36,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup src/index.ts src/client/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts src/client/index.ts --format esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "test": "vitest run --passWithNoTests"
-  },
   "dependencies": {
-    "@cfast/env": "workspace:*",
-    "@cfast/permissions": "workspace:*"
+    "@cfast/permissions": "0.2.0",
+    "@cfast/env": "0.1.1"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -63,5 +56,12 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/client/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run --passWithNoTests"
   }
-}
+}