otter-types 0.1.2

package/README.md

@@ -0,0 +1,36 @@
+# otter-types
+
+TypeScript definitions for [Otter](https://github.com/octofhir/otter) runtime.
+
+## Installation
+
+```bash
+npm install otter-types
+```
+
+This package depends on `@types/node` for Web API and Node.js type definitions.
+
+## Usage
+
+Types are automatically available when you install this package. For best results, use this `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["otter-types"],
+    "skipLibCheck": true
+  }
+}
+```
+
+## What's included
+
+- **globals.d.ts** - CommonJS support (`require`, `module`, `exports`, `__dirname`, `__filename`)
+- **sql.d.ts** - SQL and KV store APIs
+- **serve.d.ts** - HTTP server APIs (`Otter.serve()`)
+
+Web APIs (fetch, URL, TextEncoder, etc.) and Node.js APIs (fs, path, etc.) come from `@types/node`.

package/globals.d.ts

@@ -0,0 +1,104 @@
+// Otter Runtime - Global Type Definitions
+// Only includes Otter-specific globals, Web APIs come from @types/node
+
+declare global {
+    // ============================================================================
+    // CommonJS Support
+    // ============================================================================
+
+    /**
+     * Require a CommonJS module.
+     * @param id Module specifier (path or package name)
+     * @returns The module's exports
+     */
+    function require(id: string): any;
+
+    /**
+     * The require function interface with additional properties.
+     */
+    interface NodeRequire {
+        (id: string): any;
+
+        /**
+         * Resolve a module path to its absolute path.
+         */
+        resolve(id: string): string;
+
+        /**
+         * Module cache - loaded modules are cached here.
+         */
+        cache: Record<string, NodeModule>;
+
+        /**
+         * The main module (entry point).
+         */
+        main: NodeModule | undefined;
+    }
+
+    /**
+     * The module object available in CommonJS modules.
+     */
+    interface NodeModule {
+        /**
+         * The module's exports object.
+         */
+        exports: any;
+
+        /**
+         * The require function for this module.
+         */
+        require: NodeRequire;
+
+        /**
+         * The module's unique identifier.
+         */
+        id: string;
+
+        /**
+         * The absolute path to the module file.
+         */
+        filename: string;
+
+        /**
+         * Whether the module has finished loading.
+         */
+        loaded: boolean;
+
+        /**
+         * The module that first required this one.
+         */
+        parent: NodeModule | null;
+
+        /**
+         * Modules that have been required by this module.
+         */
+        children: NodeModule[];
+
+        /**
+         * The search paths for modules.
+         */
+        paths: string[];
+    }
+
+    /**
+     * The module object - available in CommonJS modules.
+     */
+    var module: NodeModule;
+
+    /**
+     * Alias to module.exports - available in CommonJS modules.
+     */
+    var exports: any;
+
+    /**
+     * The directory name of the current module - available in CommonJS modules.
+     */
+    var __dirname: string;
+
+    /**
+     * The file name of the current module - available in CommonJS modules.
+     */
+    var __filename: string;
+}
+
+export {};

package/index.d.ts

@@ -0,0 +1,8 @@
+// Otter Runtime Type Definitions
+// Entry point for @types/otter
+
+/// <reference types="node" />
+
+/// <reference path="./globals.d.ts" />
+/// <reference path="./sql.d.ts" />
+/// <reference path="./serve.d.ts" />

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "otter-types",
+  "version": "0.1.2",
+  "description": "TypeScript definitions for Otter runtime",
+  "types": "./index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octofhir/otter",
+    "directory": "packages/otter-types"
+  },
+  "keywords": ["otter", "javascript", "typescript", "types", "runtime"],
+  "dependencies": {
+    "@types/node": "*"
+  }
+}

package/serve.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Otter.serve() - High-performance HTTP/HTTPS server
+ *
+ * Supports HTTP/1.1 and HTTP/2 with ALPN negotiation for TLS connections.
+ */
+
+declare namespace Otter {
+	/**
+	 * TLS configuration for HTTPS support.
+	 */
+	interface TlsOptions {
+		/**
+		 * PEM-encoded certificate chain.
+		 */
+		cert: string | Uint8Array;
+
+		/**
+		 * PEM-encoded private key.
+		 */
+		key: string | Uint8Array;
+	}
+
+	/**
+	 * Options for Otter.serve()
+	 */
+	interface ServeOptions {
+		/**
+		 * Port to listen on.
+		 * Use 0 to get a random available port.
+		 * @default 3000
+		 */
+		port?: number;
+
+		/**
+		 * Hostname to bind to.
+		 * @default "0.0.0.0"
+		 */
+		hostname?: string;
+
+		/**
+		 * Request handler function.
+		 * Called for each incoming HTTP request.
+		 *
+		 * @param request - The incoming request
+		 * @returns A Response object or a Promise that resolves to one
+		 */
+		fetch(request: Request): Response | Promise<Response>;
+
+		/**
+		 * Error handler function.
+		 * Called when the fetch handler throws an error.
+		 *
+		 * @param error - The error that was thrown
+		 * @returns A Response object to send, or void to use default 500 response
+		 */
+		error?(error: Error): Response | void;
+
+		/**
+		 * TLS configuration for HTTPS.
+		 * If provided, the server will use HTTPS with HTTP/2 support via ALPN.
+		 */
+		tls?: TlsOptions;
+	}
+
+	/**
+	 * A running HTTP server instance.
+	 */
+	interface Server {
+		/**
+		 * The actual port the server is listening on.
+		 * Useful when port 0 was specified to get a random port.
+		 */
+		readonly port: number;
+
+		/**
+		 * The hostname the server is bound to.
+		 */
+		readonly hostname: string;
+
+		/**
+		 * The full URL of the server.
+		 */
+		readonly url: string;
+
+		/**
+		 * Stop the server gracefully.
+		 * Existing connections will be allowed to complete.
+		 */
+		stop(): void;
+
+		/**
+		 * Reload the server with new options.
+		 * Only fetch and error handlers can be changed.
+		 *
+		 * @param options - New options to apply
+		 */
+		reload(options: Partial<Pick<ServeOptions, "fetch" | "error">>): void;
+	}
+
+	/**
+	 * Start an HTTP/HTTPS server.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Basic HTTP server
+	 * const server = await Otter.serve({
+	 *   port: 3000,
+	 *   fetch(req) {
+	 *     return new Response("Hello World!");
+	 *   }
+	 * });
+	 *
+	 * // HTTPS server with HTTP/2
+	 * const httpsServer = await Otter.serve({
+	 *   port: 443,
+	 *   tls: {
+	 *     cert: await Otter.file("cert.pem").text(),
+	 *     key: await Otter.file("key.pem").text()
+	 *   },
+	 *   fetch(req) {
+	 *     return new Response("Secure!");
+	 *   }
+	 * });
+	 *
+	 * // Random port
+	 * const server = await Otter.serve({
+	 *   port: 0,
+	 *   fetch(req) {
+	 *     return new Response("Running on port " + server.port);
+	 *   }
+	 * });
+	 * console.log(`Server running at ${server.url}`);
+	 * ```
+	 *
+	 * @param options - Server configuration
+	 * @returns A promise that resolves to a Server instance
+	 */
+	function serve(options: ServeOptions): Promise<Server>;
+
+	/**
+	 * Server class constructor (for instanceof checks).
+	 */
+	const Server: {
+		prototype: Server;
+	};
+}

package/sql.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Otter SQL API
+ *
+ * Provides unified SQLite and PostgreSQL support with tagged template queries,
+ * transactions, and COPY operations (PostgreSQL only).
+ */
+
+// ============================================================================
+// SQL Module
+// ============================================================================
+
+declare module "otter" {
+	/**
+	 * Default SQL tagged template function.
+	 * Uses DATABASE_URL environment variable or falls back to SQLite :memory:.
+	 *
+	 * @example
+	 * ```typescript
+	 * import { sql } from "otter";
+	 *
+	 * const users = await sql`SELECT * FROM users`;
+	 * const user = await sql`SELECT * FROM users WHERE id = ${userId}`;
+	 * ```
+	 */
+	export const sql: SqlTaggedTemplate & SqlHelpers;
+
+	/**
+	 * SQL class for creating database connections.
+	 *
+	 * @example
+	 * ```typescript
+	 * import { SQL } from "otter";
+	 *
+	 * const db = new SQL(":memory:");
+	 * const pg = new SQL("postgres://localhost/mydb");
+	 * ```
+	 */
+	export class SQL {
+		constructor(url: string);
+		constructor(options: SQLOptions);
+
+		/** Execute a tagged template query and return results */
+		query<T = any>(
+			strings: TemplateStringsArray,
+			...values: any[]
+		): Promise<T[]>;
+
+		/** Execute a tagged template statement and return affected rows */
+		execute(strings: TemplateStringsArray, ...values: any[]): Promise<number>;
+
+		/**
+		 * Begin a transaction.
+		 *
+		 * @example
+		 * ```typescript
+		 * await db.begin(async (tx) => {
+		 *   await tx`INSERT INTO users (name) VALUES (${"Alice"})`;
+		 *   await tx`UPDATE accounts SET balance = balance - 100`;
+		 *   // auto-commit on success, auto-rollback on error
+		 * });
+		 * ```
+		 */
+		begin<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+
+		/**
+		 * Reserve a connection for exclusive use.
+		 */
+		reserve(): Promise<ReservedSQL>;
+
+		/**
+		 * COPY FROM - bulk import data (PostgreSQL only).
+		 *
+		 * @example
+		 * ```typescript
+		 * await pg.copyFrom("users", {
+		 *   columns: ["name", "email"],
+		 *   format: "csv",
+		 *   source: new Blob(["Alice,alice@example.com\n"]),
+		 * });
+		 * ```
+		 */
+		copyFrom(table: string, options: CopyFromOptions): Promise<number>;
+
+		/**
+		 * COPY TO - bulk export data (PostgreSQL only).
+		 * Returns an async iterable of chunks.
+		 *
+		 * @example
+		 * ```typescript
+		 * for await (const chunk of await pg.copyTo("users", { format: "csv" })) {
+		 *   process.stdout.write(chunk);
+		 * }
+		 * ```
+		 */
+		copyTo(
+			table: string,
+			options?: CopyToOptions,
+		): Promise<AsyncIterable<Uint8Array>>;
+
+		/**
+		 * COPY TO with a query (PostgreSQL only).
+		 */
+		copyToQuery(
+			query: string,
+			options?: CopyToOptions,
+		): Promise<AsyncIterable<Uint8Array>>;
+
+		/**
+		 * Close all connections.
+		 */
+		close(options?: { timeout?: number }): Promise<void>;
+
+		/** Get the adapter type ("sqlite" or "postgres") */
+		readonly adapter: "sqlite" | "postgres";
+
+		/** PostgreSQL error class */
+		static PostgresError: typeof PostgresError;
+
+		/** SQLite error class */
+		static SQLiteError: typeof SQLiteError;
+	}
+
+	/**
+	 * KV store function.
+	 *
+	 * @example
+	 * ```typescript
+	 * import { kv } from "otter";
+	 *
+	 * const store = kv("./data.kv");
+	 * const cache = kv(":memory:");
+	 * ```
+	 */
+	export function kv(path: string): KVStore;
+
+	// ============================================================================
+	// SQL Types
+	// ============================================================================
+
+	/**
+	 * Tagged template function for SQL queries.
+	 */
+	interface SqlTaggedTemplate {
+		<T = any>(strings: TemplateStringsArray, ...values: any[]): Promise<T[]>;
+	}
+
+	/**
+	 * SQL helper functions.
+	 */
+	interface SqlHelpers {
+		/**
+		 * Escape an identifier (table/column name).
+		 */
+		(value: string): SqlIdentifier;
+
+		/**
+		 * Insert object values.
+		 */
+		(value: object, ...columns: string[]): SqlObjectInsert;
+
+		/**
+		 * Insert array of values (for IN clause) or bulk insert.
+		 */
+		(value: any[]): SqlArrayValues;
+
+		/**
+		 * Create a PostgreSQL array literal.
+		 */
+		array(values: any[]): SqlArray;
+
+		/**
+		 * Raw SQL (use with caution!).
+		 */
+		raw(sql: string): SqlRaw;
+	}
+
+	interface SqlIdentifier {
+		__sql_type: "identifier";
+		value: string;
+	}
+
+	interface SqlObjectInsert {
+		__sql_type: "object_insert";
+		values: object | object[];
+		columns: string[] | null;
+	}
+
+	interface SqlArrayValues {
+		__sql_type: "array_in" | "object_insert";
+		values: any[];
+		columns?: string[] | null;
+	}
+
+	interface SqlArray {
+		__sql_type: "array_values";
+		values: any[];
+	}
+
+	interface SqlRaw {
+		__sql_type: "raw";
+		value: string;
+	}
+
+	/**
+	 * SQL connection options.
+	 */
+	interface SQLOptions {
+		/** Database adapter type */
+		adapter?: "postgres" | "sqlite";
+		/** Hostname for PostgreSQL */
+		hostname?: string;
+		/** Port for PostgreSQL */
+		port?: number;
+		/** Database name */
+		database?: string;
+		/** Username for PostgreSQL */
+		username?: string;
+		/** Password for PostgreSQL */
+		password?: string;
+		/** SSL mode for PostgreSQL */
+		ssl?: "disable" | "prefer" | "require";
+		/** Maximum connections for PostgreSQL pool */
+		max?: number;
+		/** Idle timeout in seconds */
+		idleTimeout?: number;
+		/** Connection timeout in seconds */
+		connectionTimeout?: number;
+	}
+
+	/**
+	 * SQL transaction.
+	 */
+	interface Transaction {
+		/** Execute a query within the transaction */
+		<T = any>(strings: TemplateStringsArray, ...values: any[]): Promise<T[]>;
+
+		/** Execute a query within the transaction */
+		query<T = any>(
+			strings: TemplateStringsArray,
+			...values: any[]
+		): Promise<T[]>;
+
+		/**
+		 * Create a savepoint.
+		 *
+		 * @example
+		 * ```typescript
+		 * await tx.savepoint(async (sp) => {
+		 *   await sp`UPDATE users SET status = 'active'`;
+		 *   if (error) throw new Error("rollback to savepoint");
+		 * });
+		 * ```
+		 */
+		savepoint<T>(fn: (sp: Transaction) => Promise<T>): Promise<T>;
+	}
+
+	/**
+	 * Reserved SQL connection.
+	 */
+	interface ReservedSQL {
+		/** Execute a query on the reserved connection */
+		query<T = any>(
+			strings: TemplateStringsArray,
+			...values: any[]
+		): Promise<T[]>;
+
+		/** Release the connection back to the pool */
+		release(): void;
+	}
+
+	/**
+	 * COPY FROM options.
+	 */
+	interface CopyFromOptions {
+		/** Column names */
+		columns?: string[];
+		/** Data format */
+		format?: "text" | "csv" | "binary";
+		/** Whether the data has a header row */
+		header?: boolean;
+		/** Column delimiter */
+		delimiter?: string;
+		/** Data source (string, Blob, or object with text() method) */
+		source: string | Blob | { text(): Promise<string> };
+		/** Called when COPY starts */
+		onCopyStart?: (info: { columns: string[] }) => void;
+		/** Called for each chunk */
+		onCopyChunk?: (bytes: number) => void;
+		/** Called when COPY completes */
+		onCopyEnd?: (result: { rowsCopied: number }) => void;
+	}
+
+	/**
+	 * COPY TO options.
+	 */
+	interface CopyToOptions {
+		/** Column names */
+		columns?: string[];
+		/** Data format */
+		format?: "text" | "csv" | "binary";
+		/** Whether to include a header row */
+		header?: boolean;
+		/** Column delimiter */
+		delimiter?: string;
+	}
+
+	/**
+	 * PostgreSQL error.
+	 */
+	class PostgresError extends Error {
+		name: "PostgresError";
+		/** PostgreSQL error code (e.g., "42P01" for undefined table) */
+		code: string;
+		/** Detailed error message */
+		detail?: string;
+		/** Hint for fixing the error */
+		hint?: string;
+	}
+
+	/**
+	 * SQLite error.
+	 */
+	class SQLiteError extends Error {
+		name: "SQLiteError";
+		/** SQLite error code (e.g., "SQLITE_CONSTRAINT") */
+		code: string;
+	}
+
+	// ============================================================================
+	// KV Store Types
+	// ============================================================================
+
+	/**
+	 * Key-value store.
+	 */
+	interface KVStore {
+		/**
+		 * Set a value for a key.
+		 * @param key The key
+		 * @param value The value (will be JSON serialized)
+		 */
+		set(key: string, value: any): void;
+
+		/**
+		 * Get a value by key.
+		 * @param key The key
+		 * @returns The value, or undefined if not found
+		 */
+		get(key: string): any;
+
+		/**
+		 * Delete a key.
+		 * @param key The key
+		 * @returns True if the key existed
+		 */
+		delete(key: string): boolean;
+
+		/**
+		 * Check if a key exists.
+		 * @param key The key
+		 * @returns True if the key exists
+		 */
+		has(key: string): boolean;
+
+		/**
+		 * Get all keys.
+		 * @returns Array of keys
+		 */
+		keys(): string[];
+
+		/**
+		 * Clear all keys.
+		 */
+		clear(): void;
+
+		/**
+		 * Get the number of keys.
+		 */
+		readonly size: number;
+
+		/**
+		 * Close the store.
+		 */
+		close(): void;
+
+		/**
+		 * Get the path to the store.
+		 */
+		readonly path: string;
+
+		/**
+		 * Check if the store is closed.
+		 */
+		readonly isClosed: boolean;
+	}
+}