@cfast/core 0.0.1 → 0.1.0

package/llms.txt

@@ -0,0 +1,167 @@
+# @cfast/core
+
+> The app object that wires @cfast/* packages together with a typed plugin system.
+
+## When to use
+
+Use `@cfast/core` when you want multiple cfast packages (auth, db, storage, etc.) to share a single per-request context without repeating initialization boilerplate in every route. It is optional -- individual packages remain fully usable standalone.
+
+## Key concepts
+
+- **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.
+- **Client provider composition**: `<app.Provider>` nests all plugin React providers in registration order. `useApp()` accesses client-side plugin exports.
+
+## API Reference
+
+### Server (`@cfast/core`)
+
+```typescript
+import { createApp, definePlugin, CfastPluginError, CfastConfigError } from "@cfast/core";
+
+// Create the app
+createApp(config: { env: TSchema; permissions: TPermissions }): App
+
+// App methods
+app.init(rawEnv: Record<string, unknown>): void       // validate env (call once in Workers entry)
+app.env(): ParsedEnv<TSchema>                          // typed validated environment
+app.context(request, context?): Promise<AppContext>     // build per-request context
+app.loader(fn: (ctx, args) => T): (args) => Promise<T> // convenience route wrapper
+app.action(fn: (ctx, args) => T): (args) => Promise<T> // convenience route wrapper
+app.use(plugin): App                                    // register a plugin (chainable)
+app.Provider: ComponentType<{ children: ReactNode }>    // composed React provider
+app.permissions: TPermissions                           // permissions config
+```
+
+### Plugin definition
+
+```typescript
+// Leaf plugin (no dependencies) -- direct form, full inference
+definePlugin({
+  name: "analytics",
+  setup(ctx) { return { track: (event: string) => {} }; },
+  Provider?: ComponentType<{ children: ReactNode }>,
+  client?: { /* client-side values for useApp() */ },
+}): CfastPlugin
+
+// Dependent plugin -- curried form, specify TRequires explicitly
+definePlugin<AuthPluginProvides>()({
+  name: "db",
+  setup(ctx) {
+    ctx.auth.user;  // typed from AuthPluginProvides
+    return { client: createDb({}) };
+  },
+}): CfastPlugin
+```
+
+### Plugin type token
+
+```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>()({ ... })
+```
+
+### Client (`@cfast/core/client`)
+
+```typescript
+import { useApp } from "@cfast/core/client";
+import { CoreContext, createCoreProvider } from "@cfast/core/client";
+
+useApp<T>(): T  // typed access to all plugins' client exports (throws outside <app.Provider>)
+```
+
+### Error classes
+
+```typescript
+CfastPluginError  // thrown when plugin setup() fails; has .pluginName and .cause
+CfastConfigError  // thrown at startup for config issues (e.g., duplicate plugin names)
+```
+
+## Usage Examples
+
+### App setup
+
+```typescript
+// app/cfast.ts
+import { createApp } from "@cfast/core";
+import { authPlugin } from "@cfast/auth";
+import { dbPlugin } from "@cfast/db";
+import { storagePlugin } from "@cfast/storage";
+
+export const app = createApp({ env: envSchema, permissions })
+  .use(authPlugin({ magicLink: { sendMagicLink: async ({ email, url }) => {} } }))
+  .use(dbPlugin({ schema }))
+  .use(storagePlugin(storageSchema));
+```
+
+### Workers entry
+
+```typescript
+// workers/app.ts
+import { app } from "~/cfast";
+export default {
+  async fetch(request, rawEnv, ctx) {
+    app.init(rawEnv);
+    return requestHandler(request, { cloudflare: { env: app.env(), ctx } });
+  },
+};
+```
+
+### Route loader
+
+```typescript
+// 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({});
+}
+
+// Using convenience wrapper:
+export const loader = app.loader(async (ctx, { params }) => {
+  return ctx.db.client.query(posts).findMany().run({});
+});
+```
+
+### Client provider
+
+```typescript
+// app/root.tsx
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html><body>
+      <app.Provider>{children}</app.Provider>
+    </body></html>
+  );
+}
+```
+
+### Wiring with @cfast/actions
+
+```typescript
+export const { createAction, composeActions } = createActions({
+  getContext: async ({ request, context }) => {
+    const ctx = await app.context(request, context);
+    return { db: ctx.db.client, user: ctx.auth.user, grants: ctx.auth.grants };
+  },
+});
+```
+
+## Integration
+
+- **@cfast/env** -- `createApp({ env: schema })` delegates to `defineEnv()`. `app.init()` calls `env.init()`, `app.env()` calls `env.get()`.
+- **@cfast/permissions** -- Accepted directly in `createApp()`. Available to all plugins.
+- **@cfast/auth, @cfast/db, @cfast/storage** -- Each ships an optional plugin for core. The plugin wraps their standalone factory and registers with `.use()`.
+- **@cfast/actions** -- Not wrapped by core. Actions have their own context mechanism. Use `app.context()` inside `createActions({ getContext })`.
+
+## 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.
+- 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).

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@cfast/core",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "App composition layer with plugin system for @cfast/* packages",
+  "keywords": [
+    "cfast",
+    "cloudflare-workers",
+    "plugin",
+    "composition",
+    "framework"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,15 +29,23 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "sideEffects": false,
   "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/permissions": "0.0.1",
-    "@cfast/env": "0.0.1"
+    "@cfast/env": "workspace:*",
+    "@cfast/permissions": "workspace:*"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -48,12 +63,5 @@
     "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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/types-B3KP3EKS.d.ts

@@ -1,49 +0,0 @@
-import { Schema, ParsedEnv } from '@cfast/env';
-import { Permissions } from '@cfast/permissions';
-import { ComponentType, ReactNode } from 'react';
-
-type CreateAppConfig<TSchema extends Schema, TPermissions extends Permissions> = {
-    env: TSchema;
-    permissions: TPermissions;
-};
-type PluginSetupContext<TRequires> = {
-    request: Request;
-    env: Record<string, unknown>;
-} & TRequires;
-type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires = {}, TClient = {}> = {
-    name: TName;
-    setup: (ctx: PluginSetupContext<TRequires>) => TProvides | Promise<TProvides>;
-    Provider?: ComponentType<{
-        children: ReactNode;
-    }>;
-    client?: TClient;
-};
-type PluginProvides<T> = T extends CfastPlugin<infer N, infer P, unknown, unknown> ? {
-    [K in N]: P;
-} : never;
-type AppContext<TSchema extends Schema, TPluginContext> = {
-    env: ParsedEnv<TSchema>;
-} & TPluginContext;
-type RouteArgs = {
-    request: Request;
-    params: Record<string, string | undefined>;
-    context: unknown;
-};
-type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContext, TClientContext> = {
-    init(rawEnv: Record<string, unknown>): void;
-    env(): ParsedEnv<TSchema>;
-    context(request: Request, context?: unknown): Promise<AppContext<TSchema, TPluginContext>>;
-    loader<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
-    action<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
-    use<TName extends string, TProvides, TClient>(plugin: CfastPlugin<TName, TProvides, TPluginContext, TClient>): App<TSchema, TPermissions, TPluginContext & {
-        [K in TName]: TProvides;
-    }, TClientContext & (TClient extends {} ? {
-        [K in TName]: TClient;
-    } : {})>;
-    Provider: ComponentType<{
-        children: ReactNode;
-    }>;
-    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 };

package/dist/types-C7BT5Gwe.d.ts

@@ -1,49 +0,0 @@
-import { Schema, ParsedEnv } from '@cfast/env';
-import { Permissions } from '@cfast/permissions';
-import { ComponentType, ReactNode } from 'react';
-
-type CreateAppConfig<TSchema extends Schema, TPermissions extends Permissions> = {
-    env: TSchema;
-    permissions: TPermissions;
-};
-type PluginSetupContext<TRequires> = {
-    request: Request;
-    env: Record<string, unknown>;
-} & TRequires;
-type CfastPlugin<TName extends string = string, TProvides = unknown, TRequires = unknown, TClient = unknown> = {
-    name: TName;
-    setup: (ctx: PluginSetupContext<TRequires>) => TProvides | Promise<TProvides>;
-    Provider?: ComponentType<{
-        children: ReactNode;
-    }>;
-    client?: TClient;
-};
-type PluginProvides<T> = T extends CfastPlugin<infer N, infer P, unknown, unknown> ? {
-    [K in N]: P;
-} : never;
-type AppContext<TSchema extends Schema, TPluginContext> = {
-    env: ParsedEnv<TSchema>;
-} & TPluginContext;
-type RouteArgs = {
-    request: Request;
-    params: Record<string, string | undefined>;
-    context: unknown;
-};
-type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContext, TClientContext> = {
-    init(rawEnv: Record<string, unknown>): void;
-    env(): ParsedEnv<TSchema>;
-    context(request: Request, context?: unknown): Promise<AppContext<TSchema, TPluginContext>>;
-    loader<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
-    action<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
-    use<TName extends string, TProvides, TClient>(plugin: CfastPlugin<TName, TProvides, TPluginContext, TClient>): App<TSchema, TPermissions, TPluginContext & {
-        [K in TName]: TProvides;
-    }, TClientContext & (TClient extends object ? {
-        [K in TName]: TClient;
-    } : unknown)>;
-    Provider: ComponentType<{
-        children: ReactNode;
-    }>;
-    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 };

package/dist/types-CcpyQoE6.d.ts

@@ -1,123 +0,0 @@
-import { Schema, ParsedEnv } from '@cfast/env';
-import { Permissions } from '@cfast/permissions';
-import { ComponentType, ReactNode } from 'react';
-
-/**
- * Configuration object for {@link createApp}.
- *
- * @typeParam TSchema - The env schema type from `@cfast/env`.
- * @typeParam TPermissions - The permissions definition from `@cfast/permissions`.
- */
-type CreateAppConfig<TSchema extends Schema, TPermissions extends Permissions> = {
-    /** The environment variable schema. Validated at `app.init()` time via `@cfast/env`. */
-    env: TSchema;
-    /** The permissions config from `definePermissions()`. Made available to all plugins. */
-    permissions: TPermissions;
-};
-/**
- * The context object passed to a plugin's `setup()` function.
- *
- * Contains the current request, validated env, and all values provided by prior plugins
- * (typed via `TRequires`).
- *
- * @typeParam TRequires - Intersection of prior plugin provides (e.g., `AuthPluginProvides`).
- */
-type PluginSetupContext<TRequires> = {
-    /** The incoming HTTP request for the current invocation. */
-    request: Request;
-    /** The validated environment bindings. */
-    env: Record<string, unknown>;
-} & TRequires;
-/**
- * A cfast plugin definition created by {@link definePlugin}.
- *
- * Plugins provide server-side context values via `setup()`, optional client-side React providers,
- * and optional client-side values accessible via `useApp()`.
- *
- * @typeParam TName - The unique plugin name, used as the namespace key in `AppContext`.
- * @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()`.
- */
-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;
-    /** 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`. */
-    Provider?: ComponentType<{
-        children: ReactNode;
-    }>;
-    /** Optional client-side values exposed via `useApp()`. */
-    client?: TClient;
-};
-/**
- * Utility type that extracts `{ [name]: ReturnType<setup> }` from a plugin definition.
- *
- * Use this to create a type token that dependent plugins can reference via `definePlugin<TRequires>()`.
- *
- * @typeParam T - A `CfastPlugin` type to extract provides from.
- */
-type PluginProvides<T> = T extends CfastPlugin<infer N, infer P, unknown, unknown> ? {
-    [K in N]: P;
-} : never;
-/**
- * The accumulated per-request context after all plugins have run.
- *
- * Contains the validated env plus each plugin's namespaced values.
- *
- * @typeParam TSchema - The env schema type.
- * @typeParam TPluginContext - The intersection of all registered plugins' provides.
- */
-type AppContext<TSchema extends Schema, TPluginContext> = {
-    /** The validated environment bindings. */
-    env: ParsedEnv<TSchema>;
-} & TPluginContext;
-/**
- * Route handler arguments passed through from React Router loaders and actions.
- */
-type RouteArgs = {
-    /** The incoming HTTP request. */
-    request: Request;
-    /** URL route parameters (e.g., `{ postId: "abc" }`). */
-    params: Record<string, string | undefined>;
-    /** The React Router context object (contains `cloudflare.env`, etc.). */
-    context: unknown;
-};
-/**
- * The app object returned by `createApp()` and extended by `.use()` calls.
- *
- * Provides methods for environment initialization, per-request context creation,
- * route handler wrappers, plugin registration, and a composed React provider.
- *
- * @typeParam TSchema - The env schema type.
- * @typeParam TPermissions - The permissions definition type.
- * @typeParam TPluginContext - The accumulated plugin context type.
- * @typeParam TClientContext - The accumulated client-side context type.
- */
-type App<TSchema extends Schema, TPermissions extends Permissions, TPluginContext, TClientContext> = {
-    /** Validates and initializes environment bindings. Call once in the Workers entry point. */
-    init(rawEnv: Record<string, unknown>): void;
-    /** Returns the typed, validated environment. */
-    env(): ParsedEnv<TSchema>;
-    /** Builds the per-request context by running each plugin's `setup()` in order. */
-    context(request: Request, context?: unknown): Promise<AppContext<TSchema, TPluginContext>>;
-    /** Convenience wrapper for React Router loaders that auto-creates the app context. */
-    loader<T>(fn: (ctx: AppContext<TSchema, TPluginContext>, args: RouteArgs) => T | Promise<T>): (args: RouteArgs) => Promise<T>;
-    /** 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 & {
-        [K in TName]: TProvides;
-    }, TClientContext & (TClient extends object ? {
-        [K in TName]: TClient;
-    } : unknown)>;
-    /** Composed React provider tree from all registered plugins. */
-    Provider: ComponentType<{
-        children: ReactNode;
-    }>;
-    /** The permissions config passed to `createApp()`. */
-    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 };