@facetlayer/prism-framework 0.4.0 → 0.4.1

package/src/endpoints/getEffectiveOperationId.ts

@@ -0,0 +1,90 @@
+import type { EndpointDefinition } from "../web/ExpressEndpointSetup.ts";
+
+/**
+ * Known bad values for operationId that indicate the user didn't set it properly.
+ * These are typically default function names that don't provide meaningful identification.
+ */
+const INVALID_OPERATION_IDS = new Set([
+    'handler',
+    'anonymous',
+    '',
+]);
+
+/**
+ * Validates that an operationId is not a known bad value.
+ */
+export function isValidOperationId(operationId: string | undefined): boolean {
+    if (operationId === undefined) {
+        return true; // undefined is fine, we'll auto-generate
+    }
+    return !INVALID_OPERATION_IDS.has(operationId);
+}
+
+/**
+ * Converts a hyphenated string to camelCase.
+ * e.g., "undo-redo-state" -> "undoRedoState"
+ * Preserves existing casing when there are no hyphens.
+ * e.g., "userId" -> "userId"
+ */
+function toCamelCase(str: string): string {
+    if (!str.includes('-')) {
+        return str;
+    }
+    return str
+        .split('-')
+        .map((part, index) => {
+            if (index === 0) {
+                return part.toLowerCase();
+            }
+            return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+        })
+        .join('');
+}
+
+/**
+ * Generates an operationId from the method and path.
+ * e.g., "GET /users/:id" -> "getUsers_id"
+ * e.g., "GET /users/:id/undo-redo-state" -> "getUsers_idUndoRedoState"
+ */
+export function generateOperationIdFromPath(method: string, path: string): string {
+    // Convert path to camelCase identifier
+    // e.g., "/users/:id/posts" -> "Users_idPosts"
+    const pathPart = path
+        .split('/')
+        .filter(Boolean)
+        .map((segment, index) => {
+            if (segment.startsWith(':') || segment.startsWith('{')) {
+                // Path parameter: :id -> _id, {id} -> _id
+                const paramName = segment.replace(/^[:{}]+|[}]+$/g, '');
+                return '_' + toCamelCase(paramName);
+            }
+            // Convert to camelCase and capitalize first letter
+            const camelCased = toCamelCase(segment);
+            return camelCased.charAt(0).toUpperCase() + camelCased.slice(1);
+        })
+        .join('');
+
+    return method.toLowerCase() + pathPart;
+}
+
+/**
+ * Gets the effective operationId for an endpoint using the priority:
+ * 1. Explicit operationId if defined
+ * 2. Handler function name if not a known bad value
+ * 3. Auto-generated from method + path
+ */
+export function getEffectiveOperationId(definition: EndpointDefinition): string {
+    // Priority 1: Explicit operationId
+    if (definition.operationId && isValidOperationId(definition.operationId)) {
+        return definition.operationId;
+    }
+
+    // Priority 2: Handler function name (if valid)
+    const handlerName = definition.handler.name;
+    if (handlerName && isValidOperationId(handlerName)) {
+        return handlerName;
+    }
+
+    // Priority 3: Auto-generate from path
+    return generateOperationIdFromPath(definition.method, definition.path);
+}

package/src/env/Env.ts

@@ -0,0 +1,23 @@
+import { config } from 'dotenv';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { z } from 'zod';
+
+// Recursively find the nearest .env file
+function findEnvFile(dir: string): string {
+  const envFile = join(dir, '.env');
+  if (existsSync(envFile)) {
+    return envFile;
+  }
+  const parentDir = dirname(dir);
+  if (parentDir === dir) {
+    throw new Error('No .env file found');
+  }
+  return findEnvFile(parentDir);
+}
+
+config({
+  quiet: true,
+  path: findEnvFile(process.cwd()),
+});
+

package/src/index.ts

@@ -0,0 +1,78 @@
+// Framework exports
+export {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  HttpError,
+  NotFoundError,
+  NotImplementedError,
+  ServiceUnavailableError,
+  UnauthorizedError,
+  ValidationError,
+  createErrorFromStatus,
+  isHttpError,
+} from './Errors.ts';
+
+
+export { createExpressApp, startServer } from './web/ExpressAppSetup.ts';
+export type { ServerSetupConfig, WebConfig } from './web/ExpressAppSetup.ts';
+
+export { getMetrics, recordHttpRequest, recordHttpResponse } from './Metrics.ts';
+
+export type { RequestContext } from './RequestContext.ts';
+export { getCurrentRequestContext, withRequestContext } from './RequestContext.ts';
+export { requestContextMiddleware } from './web/requestContextMiddleware.ts';
+
+export type { MiddlewareDefinition, ServiceDefinition } from './ServiceDefinition.ts';
+
+// Authorization exports
+export type { CookieAuthSource, AuthSource, Permission, Resource, UserPermissions } from './authorization/index.ts';
+export { Authorization } from './authorization/index.ts';
+
+// Web framework exports
+export { corsMiddleware } from './web/corsMiddleware.ts';
+export type { CorsConfig } from './web/corsMiddleware.ts';
+export type { EndpointDefinition } from './web/ExpressEndpointSetup.ts';
+export {
+  getRequestDataFromReq,
+  mountMiddleware,
+  mountMiddlewares,
+  mountPrismApp,
+} from './web/ExpressEndpointSetup.ts';
+export { localhostOnlyMiddleware } from './web/localhostOnlyMiddleware.ts';
+export { SseResponse } from './web/SseResponse.ts';
+export { createEndpoint } from './endpoints/createEndpoint.ts';
+
+// OpenAPI exports
+export type { OpenAPIDocumentInfo, ParseExpressPathForOpenAPIResult } from './web/openapi/OpenAPI.ts';
+export { generateOpenAPISchema, parseExpressPathForOpenAPI } from './web/openapi/OpenAPI.ts';
+
+// Endpoint listing exports
+export { createListingEndpoints } from './web/EndpointListing.ts';
+
+// SSE Connection Management exports
+export { ConnectionManager } from './sse/ConnectionManager.ts';
+
+// App exports
+export { PrismApp as App } from './app/PrismApp.ts';
+export type { PrismAppConfig as AppConfig } from './app/PrismApp.ts';
+
+// Launch configuration exports
+export type { LoggingSettings, LaunchConfig } from './launch/launchConfig.ts';
+export { getDatabaseConfig, getLaunchConfig, getLoggingConfig, setLaunchConfig } from './launch/launchConfig.ts';
+
+// Database setup exports
+export type { DatabaseInitializationOptions } from './databases/DatabaseInitializationOptions.ts';
+export type { MigrationBehavior } from '@facetlayer/sqlite-wrapper';
+export { getStatementsForDatabase } from './databases/DatabaseSetup.ts';
+
+// Endpoint calling exports
+export type { CallEndpointOptions } from './app/callEndpoint.ts';
+export { callEndpoint } from './app/callEndpoint.ts';
+
+// Stdin/stdout protocol exports
+export type { StdinRequest, StdinResponse, StdinServerConfig } from './stdin/StdinServer.ts';
+export { startStdinServer } from './stdin/StdinServer.ts';
+
+// Logging exports
+export { setLogStderr } from './logging/index.ts';

package/src/launch/launchConfig.ts

@@ -0,0 +1,59 @@
+import type { DatabaseInitializationOptions } from '../databases/DatabaseInitializationOptions.ts';
+import type { LoadDatabaseFn } from '@facetlayer/sqlite-wrapper';
+
+/*
+  launchConfig
+
+  This is a global settings object that is set by the entry point when the app starts up. It contains
+  settings for logging and database initialization.
+*/
+
+export interface LoggingSettings {
+  databaseFilename: string;
+  enableConsoleLogging: boolean;
+  loadDatabase: LoadDatabaseFn;
+}
+
+export interface LaunchConfig {
+  logging?: LoggingSettings;
+  database?: {
+    [databaseName: string]: DatabaseInitializationOptions;
+  };
+}
+
+let _config: LaunchConfig | undefined;
+
+export function getLaunchConfig(): LaunchConfig {
+  if (!_config) {
+    throw new Error('Launch config not initialized');
+  }
+  return _config;
+}
+
+export function setLaunchConfig(config: LaunchConfig): void {
+  if (_config) {
+    throw new Error('Launch config already initialized');
+  }
+  _config = config;
+}
+
+export function getDatabaseConfig(databaseName: string): DatabaseInitializationOptions {
+  if (!_config) {
+    throw new Error(
+      'Launch config not initialized (tried to getDatabaseConfig for: ' + databaseName + ')'
+    );
+  }
+
+  if (!_config.database[databaseName]) {
+    throw new Error('Database config not found (tried to getDatabaseConfig for: ' + databaseName + ')');
+  }
+
+  return _config.database[databaseName];
+}
+
+export function getLoggingConfig(): LoggingSettings {
+  if (!_config) {
+    throw new Error('Launch config not initialized (in getLoggingConfig)');
+  }
+  return _config.logging;
+}

package/src/list-endpoints-command.ts

@@ -7,7 +7,7 @@ export async function listEndpoints(baseUrl: string): Promise<void> {
   try {
     const response = await callEndpoint({
       baseUrl,
-      positionalArgs: ['GET', '/endpoints.json'],
+      positionalArgs: ['GET', '/api/endpoints.json'],
       namedArgs: {},
       quiet: true,
     });

package/src/logging/index.ts

@@ -0,0 +1,25 @@
+let useStderr = false;
+
+/**
+ * When enabled, logInfo writes to stderr instead of stdout.
+ * This is used in stdin protocol mode to avoid corrupting the JSON protocol on stdout.
+ */
+export function setLogStderr(enabled: boolean): void {
+    useStderr = enabled;
+}
+
+export function logInfo(...args: any[]) {
+    if (useStderr) {
+        console.error(...args);
+    } else {
+        console.log(...args);
+    }
+}
+
+export function logWarn(...args: any[]) {
+    console.warn(...args);
+}
+
+export function logError(...args: any[]) {
+    console.error(...args);
+}

package/src/sse/ConnectionManager.ts

@@ -0,0 +1,79 @@
+import type { SseResponse } from '../web/SseResponse.ts';
+
+interface SetupOptions {
+  managerName: string;
+  logDebug?: (message: string) => void;
+  logError?: (message: string, error?: any) => void;
+}
+
+interface Connection {
+  key: string;
+  sseResponse: SseResponse;
+  connectedAt: Date;
+}
+
+/*
+ * ConnectionManager
+ *
+ * This keeps an in-memory map of active connections. Each one corresponds to
+ * an active HTTP SSE request that is currently open.
+ *
+ * This class can be used to list active connections or to push a message to
+ * a connection.
+ */
+export class ConnectionManager<EventType extends object> {
+  private connections: Map<string, Connection[]> = new Map();
+  private managerName: string;
+  private logDebug: (message: string) => void;
+  private logError: (message: string, error?: any) => void;
+
+  constructor(options: SetupOptions) {
+    this.managerName = options.managerName;
+    this.logDebug = options.logDebug || (() => {});
+    this.logError = options.logError || (() => {});
+  }
+
+  addConnection(key: string, sseResponse: SseResponse): void {
+    this.logDebug(`${this.managerName} (ConnectionManager) adding connection for: ${key}`);
+
+    const connectionList = this.connections.get(key) || [];
+    const connection = {
+      key,
+      sseResponse,
+      connectedAt: new Date(),
+    };
+
+    connectionList.push(connection);
+    this.connections.set(key, connectionList);
+
+    // Clean up when connection closes
+    sseResponse.onClose(() => {
+      this.logDebug(`${this.managerName} (ConnectionManager) closed connection for: ${key}`);
+
+      const updatedList = this.connections.get(key)?.filter(c => c !== connection) || [];
+      if (updatedList.length === 0) {
+        this.connections.delete(key);
+      } else {
+        this.connections.set(key, updatedList);
+      }
+    });
+  }
+
+  getConnections(key: string): Connection[] {
+    return this.connections.get(key) || [];
+  }
+
+  async postEvent(key: string, event: EventType): Promise<void> {
+    const connections = this.getConnections(key);
+
+    for (const connection of connections) {
+      if (connection.sseResponse.isOpen()) {
+        try {
+          connection.sseResponse.send(event as object);
+        } catch (error) {
+          this.logError('Error sending SSE event:', error);
+        }
+      }
+    }
+  }
+}

package/src/stdin/StdinServer.ts

@@ -0,0 +1,129 @@
+import { createInterface } from 'readline';
+import { PrismApp } from '../app/PrismApp.ts';
+import { isHttpError } from '../Errors.ts';
+import { validateAppOrThrow } from '../app/validateApp.ts';
+import { setLogStderr } from '../logging/index.ts';
+
+/**
+ * JSON message sent from the parent process to the stdin server.
+ */
+export interface StdinRequest {
+  /** Unique request ID for correlating responses. */
+  id: string;
+  /** HTTP method (GET, POST, PUT, DELETE, PATCH). */
+  method: string;
+  /** Endpoint path, e.g. "/users" or "/users/123". */
+  path: string;
+  /** Request body / input data. */
+  body?: any;
+}
+
+/**
+ * JSON message sent back from the stdin server to the parent process.
+ */
+export interface StdinResponse {
+  /** Matches the request ID. */
+  id: string;
+  /** HTTP-style status code. */
+  status: number;
+  /** Response body. */
+  body: any;
+}
+
+export interface StdinServerConfig {
+  app: PrismApp;
+}
+
+/**
+ * Start processing requests from stdin and writing responses to stdout.
+ *
+ * Each line on stdin must be a JSON-encoded StdinRequest.
+ * Each response is a JSON-encoded StdinResponse written as a single line to stdout.
+ *
+ * When stdin closes, the process exits.
+ */
+export function startStdinServer(config: StdinServerConfig): void {
+  // Redirect logInfo to stderr so it doesn't corrupt the stdout JSON protocol
+  setLogStderr(true);
+
+  validateAppOrThrow(config.app);
+
+  const app = config.app;
+
+  const rl = createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  function sendResponse(response: StdinResponse): void {
+    process.stdout.write(JSON.stringify(response) + '\n');
+  }
+
+  function sendError(id: string | null, status: number, message: string, details?: any): void {
+    const response: StdinResponse = {
+      id: id ?? 'unknown',
+      status,
+      body: { message, ...(details ? { details } : {}) },
+    };
+    sendResponse(response);
+  }
+
+  rl.on('line', async (line: string) => {
+    let request: StdinRequest;
+
+    // Parse the JSON request
+    try {
+      request = JSON.parse(line);
+    } catch {
+      sendError(null, 400, 'Invalid JSON');
+      return;
+    }
+
+    if (!request.id || !request.method || !request.path) {
+      sendError(request?.id ?? null, 400, 'Missing required fields: id, method, path');
+      return;
+    }
+
+    try {
+      const result = await app.callEndpoint({
+        method: request.method.toUpperCase(),
+        path: request.path,
+        input: request.body ?? {},
+      });
+
+      sendResponse({
+        id: request.id,
+        status: 200,
+        body: result,
+      });
+    } catch (error: any) {
+      if (isHttpError(error)) {
+        sendResponse({
+          id: request.id,
+          status: error.statusCode,
+          body: {
+            message: error.message,
+            ...(error.details ? { details: error.details } : {}),
+          },
+        });
+      } else {
+        sendResponse({
+          id: request.id,
+          status: 500,
+          body: { message: error.message ?? 'Internal Server Error' },
+        });
+      }
+    }
+  });
+
+  rl.on('close', () => {
+    process.exit(0);
+  });
+
+  // Signal readiness to the parent process
+  sendResponse({
+    id: '_ready',
+    status: 200,
+    body: { message: 'stdin server ready' },
+  });
+}

package/src/web/EndpointListing.ts

@@ -0,0 +1,166 @@
+import { createEndpoint, type EndpointDefinition } from './ExpressEndpointSetup.ts';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import type { Response } from 'express';
+
+export function createListingEndpoints(endpoints: EndpointDefinition[]) {
+  return [
+    createEndpoint({
+      method: 'GET',
+      path: '/endpoints',
+      description: 'Lists all available endpoints in the system',
+      handler: () => {
+        const htmlContent = generateEndpointsHTML(endpoints);
+
+        return {
+          sendHttpResponse: (res: Response) => {
+            res.setHeader('Content-Type', 'text/html');
+            res.send(htmlContent);
+          },
+        };
+      },
+    }),
+
+    createEndpoint({
+      method: 'GET',
+      path: '/endpoints.json',
+      description: 'Lists all available endpoints in the system (JSON format)',
+      handler: () => {
+        const endpointsData = endpoints.map(endpoint => ({
+          method: endpoint.method,
+          path: endpoint.path,
+          description: endpoint.description || 'No description',
+        }));
+
+        return {
+          endpoints: endpointsData,
+        };
+      },
+    }),
+
+    createEndpoint({
+      method: 'GET',
+      path: '/changelog',
+      description: 'Serves the CHANGELOG.md file',
+      handler: () => {
+        const changelogPath = join(process.cwd(), 'CHANGELOG.md');
+        const changelogContent = readFileSync(changelogPath, 'utf8');
+
+          return {
+            sendHttpResponse: (res: Response) => {
+              res.setHeader('Content-Type', 'text/plain');
+              res.send(changelogContent);
+            },
+          };
+      },
+    }),
+
+    createEndpoint({
+      method: 'GET',
+      path: '/server-info',
+      description: 'Returns server information including name',
+      handler: () => {
+        return {
+          name: 'prism-framework',
+        };
+      },
+    }),
+  ];
+}
+
+function generateEndpointsHTML(endpoints: EndpointDefinition[]): string {
+  const endpointRows = endpoints
+    .map(
+      endpoint => `
+    <tr>
+      <td><code>${endpoint.method}</code></td>
+      <td><code>${endpoint.path}</code></td>
+      <td>${endpoint.description || 'No description'}</td>
+    </tr>
+  `
+    )
+    .join('');
+
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>API Endpoints</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 20px;
+            background-color: #f5f5f5;
+        }
+        .container {
+            background: white;
+            border-radius: 8px;
+            padding: 30px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+        }
+        h1 {
+            color: #333;
+            border-bottom: 3px solid #007acc;
+            padding-bottom: 10px;
+        }
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin-top: 20px;
+        }
+        th, td {
+            text-align: left;
+            padding: 12px;
+            border-bottom: 1px solid #ddd;
+        }
+        th {
+            background-color: #f8f9fa;
+            font-weight: 600;
+            color: #495057;
+        }
+        tr:hover {
+            background-color: #f8f9fa;
+        }
+        code {
+            background-color: #e9ecef;
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'Monaco', 'Consolas', monospace;
+        }
+        .method-get { color: #28a745; }
+        .method-post { color: #007bff; }
+        .method-put { color: #ffc107; }
+        .method-delete { color: #dc3545; }
+        .method-patch { color: #6f42c1; }
+        .count {
+            color: #6c757d;
+            font-size: 0.9em;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>API Endpoints</h1>
+        <p class="count">Total endpoints: <strong>${endpoints.length}</strong></p>
+
+        <table>
+            <thead>
+                <tr>
+                    <th>Method</th>
+                    <th>Path</th>
+                    <th>Description</th>
+                </tr>
+            </thead>
+            <tbody>
+                ${endpointRows}
+            </tbody>
+        </table>
+    </div>
+</body>
+</html>
+  `.trim();
+}