@flight-framework/core 0.2.6 → 0.3.0

package/README.md

@@ -1,347 +1,346 @@
-# @flight-framework/core
-
-Core primitives for Flight Framework - the agnostic full-stack framework with maximum flexibility and zero lock-in.
-
-## Features
-
-- **Multi-Render Mode** - SSR, SSG, ISR, and streaming in one unified API
-- **Framework Agnostic** - Works with React, Vue, Svelte, Solid, HTMX, and more
-- **File-Based Routing** - Automatic route discovery from filesystem
-- **Server Actions** - Type-safe server functions with form support
-- **Streaming SSR** - Out-of-order streaming with priority control
-- **Islands Architecture** - Partial hydration with any UI framework
-- **Caching System** - Pluggable cache adapters with deduplication
-- **Error Handling** - Structured errors with type guards and React integration
-- **Zero Lock-in** - Every component is replaceable
-
-## Installation
-
-```bash
-npm install @flight-framework/core
-```
-
-## Quick Start
-
-### Configuration
-
-```typescript
-// flight.config.ts
-import { defineConfig } from '@flight-framework/core';
-
-export default defineConfig({
-  server: {
-    port: 3000,
-  },
-  render: {
-    defaultMode: 'ssr',
-    streaming: true,
-  },
-});
-```
-
-### Create a Server
-
-```typescript
-import { createServer } from '@flight-framework/core';
-
-const server = createServer({
-  port: 3000,
-  routes: [
-    { path: '/', handler: homeHandler },
-    { path: '/api/*', handler: apiHandler },
-  ],
-});
-
-await server.start();
-```
-
-### File-Based Routing
-
-```typescript
-import { createFileRouter, scanRoutes } from '@flight-framework/core';
-
-const routes = await scanRoutes('./src/routes');
-const router = createFileRouter({ routes });
-
-// Routes are discovered automatically:
-// src/routes/index.page.tsx -> /
-// src/routes/about.page.tsx -> /about
-// src/routes/blog/[slug].page.tsx -> /blog/:slug
-```
-
-## Modules
-
-### Router
-
-```typescript
-import { createRouter } from '@flight-framework/core/router';
-
-const router = createRouter();
-router.add('GET', '/users/:id', userHandler);
-
-const match = router.match('GET', '/users/123');
-// { params: { id: '123' }, handler: userHandler }
-```
-
-### Cache
-
-```typescript
-import { createCache, memory, cached, dedupe } from '@flight-framework/core/cache';
-
-// Create a cache with memory adapter
-const cache = createCache({
-  adapter: memory(),
-  ttl: 60000,
-});
-
-// Cache function results
-const getUser = cached(
-  async (id: string) => fetchUser(id),
-  { ttl: 5000, key: (id) => `user:${id}` }
-);
-
-// Deduplicate concurrent requests
-const getData = dedupe(fetchData);
-```
-
-### Server Actions
-
-```typescript
-import { registerAction, executeAction, cookies } from '@flight-framework/core/actions';
-
-// Register a server action
-registerAction('createUser', async (formData: FormData) => {
-  const name = formData.get('name');
-  const user = await db.users.create({ name });
-  
-  cookies().set('user_id', user.id);
-  
-  return { success: true, user };
-});
-
-// Execute from client
-const result = await executeAction('createUser', formData);
-```
-
-### Streaming SSR
-
-```typescript
-import { 
-  createStreamingSSR, 
-  streamWithPriority 
-} from '@flight-framework/core/streaming';
-
-// Basic streaming
-const stream = await createStreamingSSR({
-  component: App,
-  props: { data },
-});
-
-// Priority-based streaming (out-of-order)
-const result = await streamWithPriority({
-  boundaries: [
-    { id: 'header', priority: 100, render: Header },
-    { id: 'sidebar', priority: 50, render: Sidebar },
-    { id: 'content', priority: 75, render: Content },
-  ],
-});
-```
-
-### Islands Architecture
-
-```typescript
-import { 
-  defineIsland, 
-  hydrateIslands,
-  createReactIslandAdapter 
-} from '@flight-framework/core/islands';
-
-// Define an island component
-const Counter = defineIsland({
-  name: 'counter',
-  component: CounterComponent,
-  hydrate: 'visible', // 'load' | 'visible' | 'idle' | 'interaction'
-});
-
-// Client-side hydration
-hydrateIslands({
-  adapter: createReactIslandAdapter(),
-});
-```
-
-### Middleware
-
-```typescript
-import { createMiddlewareChain } from '@flight-framework/core/middleware';
-
-const middleware = createMiddlewareChain([
-  async (ctx, next) => {
-    const start = Date.now();
-    await next();
-    console.log(`Request took ${Date.now() - start}ms`);
-  },
-  authMiddleware,
-  loggingMiddleware,
-]);
-```
-
-### Error Handling
-
-```typescript
-import { 
-  FlightError, 
-  createError, 
-  isFlightError,
-  createNotFound,
-  createForbidden,
-} from '@flight-framework/core/errors';
-
-// Create typed errors
-throw createNotFound('Page not found');
-throw createForbidden('Access denied');
-
-// Create custom errors
-throw createError({
-  statusCode: 422,
-  message: 'Validation failed',
-  data: { field: 'email', error: 'Invalid format' },
-});
-
-// Type guards
-if (isFlightError(error)) {
-  console.log(error.statusCode, error.digest);
-}
-```
-
-### React Integration
-
-```typescript
-import { ErrorProvider, useError, useFlightError } from '@flight-framework/core/react';
-
-// Wrap your app
-<ErrorProvider onError={console.error}>
-  <App />
-</ErrorProvider>
-
-// Use in components
-function MyComponent() {
-  const { error, clearError } = useFlightError();
-  
-  if (error) {
-    return <ErrorDisplay error={error} onRetry={clearError} />;
-  }
-  
-  return <Content />;
-}
-```
-
-### Metadata (SEO)
-
-```typescript
-import { renderMetadataToHead, type Metadata } from '@flight-framework/core';
-
-const metadata: Metadata = {
-  title: 'My Page',
-  description: 'Page description',
-  openGraph: {
-    title: 'OG Title',
-    image: '/og-image.png',
-  },
-};
-
-const headHtml = renderMetadataToHead(metadata);
-```
-
-### Route Rules (ISR/SSG)
-
-```typescript
-import { defineConfig } from '@flight-framework/core';
-
-export default defineConfig({
-  routeRules: {
-    '/': { prerender: true },
-    '/blog/**': { isr: 3600 },
-    '/api/**': { ssr: true },
-    '/static/**': { static: true },
-  },
-});
-```
-
-### Revalidation
-
-```typescript
-import { 
-  revalidatePath, 
-  revalidateTag,
-  createRevalidateHandler 
-} from '@flight-framework/core';
-
-// On-demand revalidation
-await revalidatePath('/blog/my-post');
-await revalidateTag('blog-posts');
-
-// Create revalidation API handler
-const handler = createRevalidateHandler({
-  secret: process.env.REVALIDATE_SECRET,
-});
-```
-
-## Environment Utilities
-
-```typescript
-import { 
-  isServer, 
-  isBrowser, 
-  isProduction,
-  isDevelopment 
-} from '@flight-framework/core/utils';
-
-if (isServer()) {
-  // Server-only code
-}
-
-if (isDevelopment()) {
-  console.log('Debug info');
-}
-```
-
-## Module Exports
-
-| Export | Description |
-|--------|-------------|
-| `@flight-framework/core` | Main entry with all primitives |
-| `@flight-framework/core/router` | Routing utilities |
-| `@flight-framework/core/cache` | Caching system |
-| `@flight-framework/core/server` | HTTP server |
-| `@flight-framework/core/render` | Rendering modes |
-| `@flight-framework/core/middleware` | Middleware chain |
-| `@flight-framework/core/actions` | Server actions |
-| `@flight-framework/core/streaming` | Streaming SSR |
-| `@flight-framework/core/islands` | Islands architecture |
-| `@flight-framework/core/errors` | Error handling |
-| `@flight-framework/core/react` | React integration |
-| `@flight-framework/core/rsc` | React Server Components |
-| `@flight-framework/core/config` | Configuration |
-| `@flight-framework/core/utils` | Environment utilities |
-
-## TypeScript
-
-Full TypeScript support with exported types for all APIs:
-
-```typescript
-import type {
-  FlightConfig,
-  Route,
-  RouteMatch,
-  Cache,
-  CacheAdapter,
-  Middleware,
-  FlightError,
-  Metadata,
-  StreamingHints,
-} from '@flight-framework/core';
-```
-
-## License
-
-MIT
+# @flight-framework/core
+
+Core primitives for Flight Framework, including configuration, routing, caching, streaming SSR, and server actions.
+
+## Features
+
+- Multi-render mode: SSR, SSG, ISR, and streaming
+- Framework support: React, Vue, Svelte, Solid, HTMX
+- File-based routing with automatic route discovery
+- Type-safe server actions with form support
+- Streaming SSR with priority control
+- Islands architecture for partial hydration
+- Pluggable cache adapters with deduplication
+- Structured error handling with type guards
+
+## Installation
+
+```bash
+npm install @flight-framework/core
+```
+
+## Quick Start
+
+### Configuration
+
+```typescript
+// flight.config.ts
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+  render: {
+    defaultMode: 'ssr',
+    streaming: true,
+  },
+});
+```
+
+### Create a Server
+
+```typescript
+import { createServer } from '@flight-framework/core';
+
+const server = createServer({
+  port: 3000,
+  routes: [
+    { path: '/', handler: homeHandler },
+    { path: '/api/*', handler: apiHandler },
+  ],
+});
+
+await server.start();
+```
+
+### File-Based Routing
+
+```typescript
+import { createFileRouter, scanRoutes } from '@flight-framework/core';
+
+const routes = await scanRoutes('./src/routes');
+const router = createFileRouter({ routes });
+
+// Routes are discovered automatically:
+// src/routes/index.page.tsx -> /
+// src/routes/about.page.tsx -> /about
+// src/routes/blog/[slug].page.tsx -> /blog/:slug
+```
+
+## Modules
+
+### Router
+
+```typescript
+import { createRouter } from '@flight-framework/core/router';
+
+const router = createRouter();
+router.add('GET', '/users/:id', userHandler);
+
+const match = router.match('GET', '/users/123');
+// { params: { id: '123' }, handler: userHandler }
+```
+
+### Cache
+
+```typescript
+import { createCache, memory, cached, dedupe } from '@flight-framework/core/cache';
+
+// Create a cache with memory adapter
+const cache = createCache({
+  adapter: memory(),
+  ttl: 60000,
+});
+
+// Cache function results
+const getUser = cached(
+  async (id: string) => fetchUser(id),
+  { ttl: 5000, key: (id) => `user:${id}` }
+);
+
+// Deduplicate concurrent requests
+const getData = dedupe(fetchData);
+```
+
+### Server Actions
+
+```typescript
+import { registerAction, executeAction, cookies } from '@flight-framework/core/actions';
+
+// Register a server action
+registerAction('createUser', async (formData: FormData) => {
+  const name = formData.get('name');
+  const user = await db.users.create({ name });
+  
+  cookies().set('user_id', user.id);
+  
+  return { success: true, user };
+});
+
+// Execute from client
+const result = await executeAction('createUser', formData);
+```
+
+### Streaming SSR
+
+```typescript
+import { 
+  createStreamingSSR, 
+  streamWithPriority 
+} from '@flight-framework/core/streaming';
+
+// Basic streaming
+const stream = await createStreamingSSR({
+  component: App,
+  props: { data },
+});
+
+// Priority-based streaming (out-of-order)
+const result = await streamWithPriority({
+  boundaries: [
+    { id: 'header', priority: 100, render: Header },
+    { id: 'sidebar', priority: 50, render: Sidebar },
+    { id: 'content', priority: 75, render: Content },
+  ],
+});
+```
+
+### Islands Architecture
+
+```typescript
+import { 
+  defineIsland, 
+  hydrateIslands,
+  createReactIslandAdapter 
+} from '@flight-framework/core/islands';
+
+// Define an island component
+const Counter = defineIsland({
+  name: 'counter',
+  component: CounterComponent,
+  hydrate: 'visible', // 'load' | 'visible' | 'idle' | 'interaction'
+});
+
+// Client-side hydration
+hydrateIslands({
+  adapter: createReactIslandAdapter(),
+});
+```
+
+### Middleware
+
+```typescript
+import { createMiddlewareChain } from '@flight-framework/core/middleware';
+
+const middleware = createMiddlewareChain([
+  async (ctx, next) => {
+    const start = Date.now();
+    await next();
+    console.log(`Request took ${Date.now() - start}ms`);
+  },
+  authMiddleware,
+  loggingMiddleware,
+]);
+```
+
+### Error Handling
+
+```typescript
+import { 
+  FlightError, 
+  createError, 
+  isFlightError,
+  createNotFound,
+  createForbidden,
+} from '@flight-framework/core/errors';
+
+// Create typed errors
+throw createNotFound('Page not found');
+throw createForbidden('Access denied');
+
+// Create custom errors
+throw createError({
+  statusCode: 422,
+  message: 'Validation failed',
+  data: { field: 'email', error: 'Invalid format' },
+});
+
+// Type guards
+if (isFlightError(error)) {
+  console.log(error.statusCode, error.digest);
+}
+```
+
+### React Integration
+
+```typescript
+import { ErrorProvider, useError, useFlightError } from '@flight-framework/core/react';
+
+// Wrap your app
+<ErrorProvider onError={console.error}>
+  <App />
+</ErrorProvider>
+
+// Use in components
+function MyComponent() {
+  const { error, clearError } = useFlightError();
+  
+  if (error) {
+    return <ErrorDisplay error={error} onRetry={clearError} />;
+  }
+  
+  return <Content />;
+}
+```
+
+### Metadata (SEO)
+
+```typescript
+import { renderMetadataToHead, type Metadata } from '@flight-framework/core';
+
+const metadata: Metadata = {
+  title: 'My Page',
+  description: 'Page description',
+  openGraph: {
+    title: 'OG Title',
+    image: '/og-image.png',
+  },
+};
+
+const headHtml = renderMetadataToHead(metadata);
+```
+
+### Route Rules (ISR/SSG)
+
+```typescript
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/blog/**': { isr: 3600 },
+    '/api/**': { ssr: true },
+    '/static/**': { static: true },
+  },
+});
+```
+
+### Revalidation
+
+```typescript
+import { 
+  revalidatePath, 
+  revalidateTag,
+  createRevalidateHandler 
+} from '@flight-framework/core';
+
+// On-demand revalidation
+await revalidatePath('/blog/my-post');
+await revalidateTag('blog-posts');
+
+// Create revalidation API handler
+const handler = createRevalidateHandler({
+  secret: process.env.REVALIDATE_SECRET,
+});
+```
+
+## Environment Utilities
+
+```typescript
+import { 
+  isServer, 
+  isBrowser, 
+  isProduction,
+  isDevelopment 
+} from '@flight-framework/core/utils';
+
+if (isServer()) {
+  // Server-only code
+}
+
+if (isDevelopment()) {
+  console.log('Debug info');
+}
+```
+
+## Module Exports
+
+| Export | Description |
+|--------|-------------|
+| `@flight-framework/core` | Main entry with all primitives |
+| `@flight-framework/core/router` | Routing utilities |
+| `@flight-framework/core/cache` | Caching system |
+| `@flight-framework/core/server` | HTTP server |
+| `@flight-framework/core/render` | Rendering modes |
+| `@flight-framework/core/middleware` | Middleware chain |
+| `@flight-framework/core/actions` | Server actions |
+| `@flight-framework/core/streaming` | Streaming SSR |
+| `@flight-framework/core/islands` | Islands architecture |
+| `@flight-framework/core/errors` | Error handling |
+| `@flight-framework/core/react` | React integration |
+| `@flight-framework/core/rsc` | React Server Components |
+| `@flight-framework/core/config` | Configuration |
+| `@flight-framework/core/utils` | Environment utilities |
+
+## TypeScript
+
+Full TypeScript support with exported types for all APIs:
+
+```typescript
+import type {
+  FlightConfig,
+  Route,
+  RouteMatch,
+  Cache,
+  CacheAdapter,
+  Middleware,
+  FlightError,
+  Metadata,
+  StreamingHints,
+} from '@flight-framework/core';
+```
+
+## License
+
+MIT