@flight-framework/core 0.2.5 → 0.2.6

package/README.md

@@ -0,0 +1,347 @@
+# @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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flight-framework/core",
-    "version": "0.2.5",
+    "version": "0.2.6",
     "description": "Core primitives for Flight Framework - routing, rendering, caching",
     "keywords": [
         "flight",