@b9g/platform 0.1.0

package/src/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Core Platform interface and configuration types for Shovel deployment adapters
+ */
+import type { CacheStorage } from "@b9g/cache/cache-storage";
+export { loadCacheAdapter, loadFilesystemAdapter, resolveCacheAdapter, resolveFilesystemAdapter, CACHE_ALIASES, FILESYSTEM_ALIASES, } from "./adapter-registry.js";
+export { BasePlatform } from "./base-platform.js";
+export { detectRuntime, detectDevelopmentPlatform, detectPlatforms, getBestPlatformDetection, resolvePlatform, createPlatform, displayPlatformInfo, } from "./detection.js";
+/**
+ * Cache backend configuration
+ * Type can be a blessed alias or full package name
+ */
+export interface CacheBackendConfig {
+    /** Cache backend type - blessed alias (memory, redis, kv) or package name (@custom/cache) */
+    type?: string;
+    /** Maximum number of entries (for memory/LRU caches) */
+    maxEntries?: number;
+    /** Time-to-live in milliseconds or string format (e.g., '5m', '1h') */
+    ttl?: number | string;
+    /** Directory for filesystem cache */
+    dir?: string;
+    /** Redis connection string */
+    url?: string;
+    /** Custom cache factory function */
+    factory?: () => any;
+}
+/**
+ * Cache configuration for different cache types
+ */
+export interface CacheConfig {
+    /** Page/HTML cache configuration */
+    pages?: CacheBackendConfig;
+    /** API response cache configuration */
+    api?: CacheBackendConfig;
+    /** Static file cache configuration */
+    static?: CacheBackendConfig;
+    /** Custom named caches */
+    [name: string]: CacheBackendConfig | undefined;
+}
+/**
+ * Static file serving configuration
+ */
+export interface StaticConfig {
+    /** Public URL path prefix */
+    publicPath?: string;
+    /** Output directory for built assets */
+    outputDir?: string;
+    /** Asset manifest file path */
+    manifest?: string;
+    /** Development mode (serve from source) */
+    dev?: boolean;
+    /** Source directory for development */
+    sourceDir?: string;
+    /** Cache configuration for static files */
+    cache?: {
+        name?: string;
+        ttl?: string | number;
+    };
+}
+/**
+ * CORS configuration
+ */
+export interface CorsConfig {
+    /** Allowed origins */
+    origin?: boolean | string | string[] | RegExp | ((origin: string) => boolean);
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Exposed headers */
+    exposedHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Preflight cache duration */
+    maxAge?: number;
+}
+/**
+ * Filesystem adapter configuration
+ */
+export interface FilesystemConfig {
+    /** Filesystem adapter type - blessed alias (memory, s3, r2) or package name (@custom/fs) */
+    type?: string;
+    /** Region for cloud storage */
+    region?: string;
+    /** Access credentials */
+    credentials?: {
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        token?: string;
+    };
+    /** Additional adapter-specific options */
+    [key: string]: any;
+}
+/**
+ * Platform configuration from CLI flags
+ */
+export interface PlatformConfig {
+    /** Cache configuration */
+    caches?: CacheConfig;
+    /** Filesystem adapter configuration */
+    filesystem?: FilesystemConfig;
+}
+/**
+ * Server options for platform implementations
+ */
+export interface ServerOptions {
+    /** Port to listen on */
+    port?: number;
+    /** Host to bind to */
+    host?: string;
+    /** Hostname for URL generation */
+    hostname?: string;
+    /** Enable compression */
+    compression?: boolean;
+    /** CORS configuration */
+    cors?: CorsConfig;
+    /** Custom headers to add to all responses */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Development mode settings */
+    development?: {
+        /** Enable hot reloading */
+        hotReload?: boolean;
+        /** Source maps support */
+        sourceMaps?: boolean;
+        /** Verbose logging */
+        verbose?: boolean;
+    };
+}
+/**
+ * Request handler function (Web Fetch API compatible)
+ */
+export type Handler = (request: Request, context?: any) => Promise<Response> | Response;
+/**
+ * ServiceWorker entrypoint options
+ */
+export interface ServiceWorkerOptions {
+    /** Enable hot reloading */
+    hotReload?: boolean;
+    /** Cache configuration to pass to platform event */
+    caches?: CacheConfig;
+    /** Additional context to provide */
+    context?: any;
+}
+/**
+ * ServiceWorker instance returned by platform
+ */
+export interface ServiceWorkerInstance {
+    /** The ServiceWorker runtime */
+    runtime: any;
+    /** Handle HTTP request */
+    handleRequest(request: Request): Promise<Response>;
+    /** Install the ServiceWorker */
+    install(): Promise<void>;
+    /** Activate the ServiceWorker */
+    activate(): Promise<void>;
+    /** Collect routes for static generation */
+    collectStaticRoutes(outDir: string, baseUrl?: string): Promise<string[]>;
+    /** Check if ready to handle requests */
+    readonly ready: boolean;
+    /** Dispose of resources */
+    dispose(): Promise<void>;
+}
+/**
+ * Server instance returned by platform.createServer()
+ */
+export interface Server {
+    /** Start listening for requests */
+    listen(): Promise<void> | void;
+    /** Stop the server */
+    close(): Promise<void> | void;
+    /** Get server URL */
+    url?: string;
+    /** Platform-specific server instance */
+    instance?: any;
+}
+/**
+ * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
+ *
+ * The core responsibility: "Take a ServiceWorker-style app file and make it run in this environment"
+ */
+export interface Platform {
+    /**
+     * Platform name for identification
+     */
+    readonly name: string;
+    /**
+     * Build artifacts filesystem (install-time only)
+     * Available during install handlers to copy built files to runtime storage
+     */
+    readonly distDir: FileSystemDirectoryHandle;
+    /**
+     * THE MAIN JOB - Load and run a ServiceWorker-style entrypoint
+     * This is where all the platform-specific complexity lives
+     */
+    loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
+    /**
+     * SUPPORTING UTILITY - Create cache storage with platform-optimized backends
+     * Automatically selects optimal cache types when not specified:
+     * - Node.js: filesystem for persistence, memory for API
+     * - Cloudflare: KV for persistence, memory for fast access
+     * - Bun: filesystem with optimized writes
+     */
+    createCaches(config?: CacheConfig): Promise<CacheStorage>;
+    /**
+     * SUPPORTING UTILITY - Create server instance for this platform
+     */
+    createServer(handler: Handler, options?: ServerOptions): Server;
+    /**
+     * SUPPORTING UTILITY - Get filesystem root for bucket/container name
+     * Maps directly to cloud storage buckets (S3, R2) or local directories
+     * @param bucketName - The bucket/container/directory name
+     */
+    getFileSystemRoot(bucketName: string): Promise<FileSystemDirectoryHandle>;
+}
+/**
+ * Platform detection result
+ */
+export interface PlatformDetection {
+    /** Detected platform name */
+    platform: string;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Detection reasons */
+    reasons: string[];
+}
+/**
+ * Platform registry for auto-detection
+ */
+export interface PlatformRegistry {
+    /** Register a platform implementation */
+    register(name: string, platform: Platform): void;
+    /** Get platform by name */
+    get(name: string): Platform | undefined;
+    /** Detect current platform */
+    detect(): PlatformDetection;
+    /** Get all registered platforms */
+    list(): string[];
+}

package/src/types.js

@@ -0,0 +1,36 @@
+/// <reference types="./types.d.ts" />
+// src/types.ts
+import {
+  loadCacheAdapter,
+  loadFilesystemAdapter,
+  resolveCacheAdapter,
+  resolveFilesystemAdapter,
+  CACHE_ALIASES,
+  FILESYSTEM_ALIASES
+} from "./adapter-registry.js";
+import { BasePlatform } from "./base-platform.js";
+import {
+  detectRuntime,
+  detectDevelopmentPlatform,
+  detectPlatforms,
+  getBestPlatformDetection,
+  resolvePlatform,
+  createPlatform,
+  displayPlatformInfo
+} from "./detection.js";
+export {
+  BasePlatform,
+  CACHE_ALIASES,
+  FILESYSTEM_ALIASES,
+  createPlatform,
+  detectDevelopmentPlatform,
+  detectPlatforms,
+  detectRuntime,
+  displayPlatformInfo,
+  getBestPlatformDetection,
+  loadCacheAdapter,
+  loadFilesystemAdapter,
+  resolveCacheAdapter,
+  resolveFilesystemAdapter,
+  resolvePlatform
+};

package/src/utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Utility functions for platform implementations
+ */
+import type { CacheBackendConfig } from "./types.js";
+/**
+ * Parse TTL string to milliseconds
+ */
+export declare function parseTTL(ttl: string | number | undefined): number | undefined;
+/**
+ * Merge cache configurations with defaults
+ */
+export declare function mergeCacheConfig(userConfig: CacheBackendConfig | undefined, defaults: Partial<CacheBackendConfig>): CacheBackendConfig;
+/**
+ * Validate cache backend configuration
+ */
+export declare function validateCacheConfig(config: CacheBackendConfig): void;
+/**
+ * Create CORS headers from configuration
+ */
+export declare function createCorsHeaders(corsConfig: any, // CorsConfig but avoiding circular import
+request: Request): Headers;
+/**
+ * Merge headers from multiple sources
+ */
+export declare function mergeHeaders(...headerSources: (Headers | Record<string, string> | undefined)[]): Headers;
+/**
+ * Check if request is a preflight CORS request
+ */
+export declare function isPreflightRequest(request: Request): boolean;
+/**
+ * Create a preflight response
+ */
+export declare function createPreflightResponse(corsConfig: any, request: Request): Response;

package/src/utils.js

@@ -0,0 +1,139 @@
+/// <reference types="./utils.d.ts" />
+// src/utils.ts
+function parseTTL(ttl) {
+  if (typeof ttl === "number") {
+    return ttl;
+  }
+  if (typeof ttl !== "string") {
+    return void 0;
+  }
+  const match = ttl.match(/^(\d+)\s*(ms|s|m|h|d)?$/);
+  if (!match) {
+    throw new Error(
+      `Invalid TTL format: ${ttl}. Use format like '5m', '1h', '30s'`
+    );
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2] || "ms";
+  const multipliers = {
+    ms: 1,
+    s: 1e3,
+    m: 60 * 1e3,
+    h: 60 * 60 * 1e3,
+    d: 24 * 60 * 60 * 1e3
+  };
+  return value * multipliers[unit];
+}
+function mergeCacheConfig(userConfig, defaults) {
+  return {
+    type: "memory",
+    ...defaults,
+    ...userConfig
+  };
+}
+function validateCacheConfig(config) {
+  const validTypes = ["memory", "filesystem", "redis", "kv", "custom"];
+  if (!validTypes.includes(config.type)) {
+    throw new Error(
+      `Invalid cache type '${config.type}'. Must be one of: ${validTypes.join(", ")}`
+    );
+  }
+  if (config.type === "filesystem" && !config.dir) {
+    throw new Error("Filesystem cache requires a directory (dir) option");
+  }
+  if (config.type === "redis" && !config.url) {
+    throw new Error("Redis cache requires a connection URL (url) option");
+  }
+  if (config.type === "custom" && !config.factory) {
+    throw new Error("Custom cache requires a factory function");
+  }
+  if (config.maxEntries !== void 0 && config.maxEntries <= 0) {
+    throw new Error("maxEntries must be a positive number");
+  }
+  if (config.ttl !== void 0) {
+    try {
+      parseTTL(config.ttl);
+    } catch (error) {
+      throw new Error(`Invalid TTL configuration: ${error.message}`);
+    }
+  }
+}
+function createCorsHeaders(corsConfig, request) {
+  const headers = new Headers();
+  if (!corsConfig) {
+    return headers;
+  }
+  const origin = request.headers.get("origin");
+  if (corsConfig.origin === true) {
+    headers.set("Access-Control-Allow-Origin", "*");
+  } else if (typeof corsConfig.origin === "string") {
+    headers.set("Access-Control-Allow-Origin", corsConfig.origin);
+  } else if (Array.isArray(corsConfig.origin)) {
+    if (origin && corsConfig.origin.includes(origin)) {
+      headers.set("Access-Control-Allow-Origin", origin);
+    }
+  } else if (corsConfig.origin instanceof RegExp) {
+    if (origin && corsConfig.origin.test(origin)) {
+      headers.set("Access-Control-Allow-Origin", origin);
+    }
+  } else if (typeof corsConfig.origin === "function") {
+    if (origin && corsConfig.origin(origin)) {
+      headers.set("Access-Control-Allow-Origin", origin);
+    }
+  }
+  if (corsConfig.methods) {
+    headers.set("Access-Control-Allow-Methods", corsConfig.methods.join(", "));
+  }
+  if (corsConfig.allowedHeaders) {
+    headers.set(
+      "Access-Control-Allow-Headers",
+      corsConfig.allowedHeaders.join(", ")
+    );
+  }
+  if (corsConfig.exposedHeaders) {
+    headers.set(
+      "Access-Control-Expose-Headers",
+      corsConfig.exposedHeaders.join(", ")
+    );
+  }
+  if (corsConfig.credentials) {
+    headers.set("Access-Control-Allow-Credentials", "true");
+  }
+  if (corsConfig.maxAge !== void 0) {
+    headers.set("Access-Control-Max-Age", corsConfig.maxAge.toString());
+  }
+  return headers;
+}
+function mergeHeaders(...headerSources) {
+  const result = new Headers();
+  for (const source of headerSources) {
+    if (!source)
+      continue;
+    if (source instanceof Headers) {
+      for (const [key, value] of source.entries()) {
+        result.set(key, value);
+      }
+    } else {
+      for (const [key, value] of Object.entries(source)) {
+        result.set(key, value);
+      }
+    }
+  }
+  return result;
+}
+function isPreflightRequest(request) {
+  return request.method === "OPTIONS" && request.headers.has("access-control-request-method");
+}
+function createPreflightResponse(corsConfig, request) {
+  const headers = createCorsHeaders(corsConfig, request);
+  return new Response(null, { status: 204, headers });
+}
+export {
+  createCorsHeaders,
+  createPreflightResponse,
+  isPreflightRequest,
+  mergeCacheConfig,
+  mergeHeaders,
+  parseTTL,
+  validateCacheConfig
+};