@dotdo/postgres 0.1.0

package/dist/observability/types.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @module observability/types
+ *
+ * Type definitions for the OpenTelemetry-compatible observability layer.
+ * Follows standard OTel patterns adapted for Cloudflare Workers.
+ *
+ * ## Core Concepts
+ *
+ * - **Spans**: Represent a single operation within a trace. Each span has a name,
+ *   start/end time, attributes, events, and status.
+ * - **Traces**: A collection of spans that share a common trace ID, representing
+ *   an end-to-end request flow.
+ * - **Metrics**: Numerical measurements like counters, gauges, and histograms.
+ * - **Context**: Propagated state (trace ID, span ID) that links operations together.
+ *
+ * ## Memory Considerations for Cloudflare Workers
+ *
+ * All types are designed to minimize memory allocation within the 128MB Worker limit:
+ * - Use primitive types where possible
+ * - Avoid deep nesting in attribute values
+ * - Span events and links are optional to reduce memory when not needed
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import type { Span, SpanContext, SpanAttributes } from '@dotdo/postgres/observability'
+ * import { SpanStatusCode, SpanKind } from '@dotdo/postgres/observability'
+ *
+ * // Type-safe span attributes
+ * const attributes: SpanAttributes = {
+ *   'db.system': 'postgresql',
+ *   'db.statement': 'SELECT * FROM users',
+ *   'db.rows_returned': 10,
+ * }
+ *
+ * // Span context for distributed tracing
+ * const context: SpanContext = {
+ *   traceId: '0af7651916cd43dd8448eb211c80319c',
+ *   spanId: 'b7ad6b7169203331',
+ *   traceFlags: 1, // Sampled
+ * }
+ * ```
+ */
+/**
+ * Span status codes following OpenTelemetry conventions.
+ *
+ * Used to indicate the outcome of a span's operation:
+ * - `OK`: Operation completed successfully
+ * - `UNSET`: Status not set (default for new spans)
+ * - `ERROR`: Operation failed with an error
+ *
+ * @example
+ * ```typescript
+ * span.setStatus({ code: SpanStatusCode.OK })
+ * span.setStatus({ code: SpanStatusCode.ERROR, message: 'Query timeout' })
+ * ```
+ */
+export declare enum SpanStatusCode {
+    /** The operation completed without errors */
+    OK = 0,
+    /** The operation was not executed */
+    UNSET = 1,
+    /** The operation contained an error */
+    ERROR = 2
+}
+/**
+ * Span kind following OpenTelemetry conventions.
+ *
+ * Indicates the relationship between the span and its parent:
+ * - `INTERNAL`: Default kind for internal operations
+ * - `SERVER`: Handling an incoming request (e.g., HTTP server, RPC handler)
+ * - `CLIENT`: Initiating an outgoing request (e.g., database query, HTTP client)
+ * - `PRODUCER`: Creating a message for async processing
+ * - `CONSUMER`: Processing a message from a queue
+ *
+ * For postgres.do operations:
+ * - Use `CLIENT` for database queries
+ * - Use `SERVER` for Durable Object fetch handlers
+ * - Use `INTERNAL` for cache operations and internal processing
+ *
+ * @example
+ * ```typescript
+ * // Database query span
+ * const span = tracer.startSpan('postgres.query', {
+ *   kind: SpanKind.CLIENT,
+ *   attributes: { 'db.system': 'postgresql' },
+ * })
+ * ```
+ */
+export declare enum SpanKind {
+    /** Default span kind - internal operation */
+    INTERNAL = 0,
+    /** Server-side handling of an incoming request */
+    SERVER = 1,
+    /** Client-side operation initiating a request */
+    CLIENT = 2,
+    /** Producer of a message */
+    PRODUCER = 3,
+    /** Consumer of a message */
+    CONSUMER = 4
+}
+/**
+ * Attribute value types supported in spans.
+ *
+ * Following OpenTelemetry semantic conventions, attribute values can be:
+ * - Primitive types: `string`, `number`, `boolean`
+ * - Homogeneous arrays: `string[]`, `number[]`, `boolean[]`
+ *
+ * **Memory Note**: For Cloudflare Workers, prefer simple values over arrays
+ * when possible to minimize memory allocation.
+ */
+export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Span attributes as key-value pairs.
+ *
+ * Keys should follow OpenTelemetry semantic conventions where applicable:
+ * - `db.*` for database operations
+ * - `http.*` for HTTP operations
+ * - `cache.*` for cache operations
+ * - `do.*` for Durable Object operations (postgres.do specific)
+ *
+ * **Note**: Optional properties in extending interfaces use `AttributeValue | undefined`
+ */
+export type SpanAttributes = Record<string, AttributeValue | undefined>;
+/**
+ * Span context for distributed tracing.
+ *
+ * Contains the identifiers needed to correlate spans across services and
+ * propagate trace context through headers (W3C Trace Context format).
+ *
+ * @example Creating a child context
+ * ```typescript
+ * import { createChildContext } from '@dotdo/postgres/observability'
+ *
+ * const parentContext = extractSpanContext(request.headers)
+ * const childContext = createChildContext(parentContext)
+ * ```
+ */
+export interface SpanContext {
+    /**
+     * Unique trace identifier (16 bytes = 32 hex characters).
+     * All spans in a trace share this ID.
+     */
+    traceId: string;
+    /**
+     * Unique span identifier (8 bytes = 16 hex characters).
+     */
+    spanId: string;
+    /**
+     * Parent span identifier (optional).
+     */
+    parentSpanId?: string | undefined;
+    /**
+     * Trace flags controlling sampling and other behaviors.
+     * Bit 0: Sampled flag (1 = sampled, 0 = not sampled)
+     */
+    traceFlags: number;
+    /**
+     * Trace state for vendor-specific data.
+     */
+    traceState?: string | undefined;
+}
+/**
+ * Span event representing a point-in-time occurrence
+ */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Timestamp in milliseconds */
+    timestamp: number;
+    /** Event attributes */
+    attributes?: SpanAttributes | undefined;
+}
+/**
+ * Span link to other spans
+ */
+export interface SpanLink {
+    /** Linked span context */
+    context: SpanContext;
+    /** Link attributes */
+    attributes?: SpanAttributes | undefined;
+}
+/**
+ * Span representing a single operation
+ */
+export interface Span {
+    /** Span name */
+    name: string;
+    /** Span context */
+    context: SpanContext;
+    /** Span kind */
+    kind: SpanKind;
+    /** Start timestamp in milliseconds */
+    startTime: number;
+    /** End timestamp in milliseconds (set when span ends) */
+    endTime?: number | undefined;
+    /** Span status */
+    status: SpanStatus;
+    /** Span attributes */
+    attributes: SpanAttributes;
+    /** Span events */
+    events: SpanEvent[];
+    /** Span links */
+    links: SpanLink[];
+    /** Resource attributes (service info) */
+    resource: SpanAttributes;
+}
+/**
+ * Span status
+ */
+export interface SpanStatus {
+    /** Status code */
+    code: SpanStatusCode;
+    /** Optional status message (for errors) */
+    message?: string | undefined;
+}
+/**
+ * Options for creating a span
+ */
+export interface SpanOptions {
+    /** Span kind (default: INTERNAL) */
+    kind?: SpanKind | undefined;
+    /** Initial attributes */
+    attributes?: SpanAttributes | undefined;
+    /** Parent span context */
+    parent?: SpanContext | undefined;
+    /** Span links */
+    links?: SpanLink[] | undefined;
+    /** Custom start time in milliseconds */
+    startTime?: number | undefined;
+}
+/**
+ * Active span interface for manipulation
+ */
+export interface ActiveSpan {
+    /** Set an attribute on the span */
+    setAttribute(key: string, value: AttributeValue): this;
+    /** Set multiple attributes on the span */
+    setAttributes(attributes: SpanAttributes): this;
+    /** Add an event to the span */
+    addEvent(name: string, attributes?: SpanAttributes, timestamp?: number): this;
+    /** Set the span status */
+    setStatus(status: SpanStatus): this;
+    /** Record an exception */
+    recordException(error: Error | string, attributes?: SpanAttributes): this;
+    /** End the span */
+    end(endTime?: number): void;
+    /** Get the span context */
+    getContext(): SpanContext;
+    /** Check if the span is recording */
+    isRecording(): boolean;
+}
+/**
+ * Tracer interface for creating spans.
+ *
+ * The primary entry point for distributed tracing. Use a tracer to create spans
+ * that track operations in your application.
+ *
+ * @example Basic tracing
+ * ```typescript
+ * const result = await tracer.startActiveSpan('postgres.query', async (span) => {
+ *   span.setAttribute('db.statement', sql)
+ *   const result = await pg.query(sql)
+ *   span.setAttribute('db.rows_returned', result.rowCount)
+ *   return result
+ * })
+ * ```
+ */
+export interface Tracer {
+    /** Start a new span */
+    startSpan(name: string, options?: SpanOptions): ActiveSpan;
+    /** Start a span and run a callback with it active */
+    startActiveSpan<T>(name: string, fn: (span: ActiveSpan) => T | Promise<T>): T | Promise<T>;
+    /** Start a span and run a callback with it active (with options) */
+    startActiveSpan<T>(name: string, options: SpanOptions, fn: (span: ActiveSpan) => T | Promise<T>): T | Promise<T>;
+}
+/**
+ * Tracer provider configuration
+ */
+export interface TracerConfig {
+    /** Service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string | undefined;
+    /** Environment (production, staging, etc.) */
+    environment?: string | undefined;
+    /** Sampling rate (0.0 to 1.0) */
+    samplingRate?: number | undefined;
+    /** Additional resource attributes */
+    resourceAttributes?: SpanAttributes | undefined;
+}
+/**
+ * Span exporter interface
+ */
+export interface SpanExporter {
+    /** Export spans */
+    export(spans: Span[]): Promise<void>;
+    /** Shutdown the exporter */
+    shutdown(): Promise<void>;
+}
+/**
+ * Console exporter configuration
+ */
+export interface ConsoleExporterConfig {
+    /** Log level (debug, info, warn, error) */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /** Pretty print output */
+    prettyPrint?: boolean | undefined;
+}
+/**
+ * Query execution span attributes
+ */
+export interface QuerySpanAttributes extends SpanAttributes {
+    'db.system': 'postgresql';
+    'db.operation'?: string | undefined;
+    'db.statement'?: string | undefined;
+    'db.name'?: string | undefined;
+    'db.rows_affected'?: number | undefined;
+    'db.rows_returned'?: number | undefined;
+    'db.duration_ms': number;
+    'db.cached'?: boolean | undefined;
+}
+/**
+ * Cache operation span attributes
+ */
+export interface CacheSpanAttributes extends SpanAttributes {
+    'cache.operation': 'get' | 'put' | 'delete' | 'has';
+    'cache.hit'?: boolean | undefined;
+    'cache.key'?: string | undefined;
+    'cache.tier'?: 'cache' | 'do' | 'r2';
+    'cache.bytes'?: number | undefined;
+    'cache.duration_ms': number;
+}
+/**
+ * Durable Object lifecycle span attributes
+ */
+export interface DOLifecycleSpanAttributes extends SpanAttributes {
+    'do.operation': 'activation' | 'hibernation' | 'fetch' | 'alarm';
+    'do.id': string;
+    'do.name'?: string | undefined;
+    'do.duration_ms': number;
+    'do.storage_used'?: number | undefined;
+}
+/**
+ * Error tracking attributes
+ */
+export interface ErrorSpanAttributes extends SpanAttributes {
+    'error.type': string;
+    'error.message': string;
+    'error.stack'?: string | undefined;
+    'error.code'?: string | undefined;
+    'error.recoverable'?: boolean | undefined;
+}
+/**
+ * Metrics collector interface for tracking counters, gauges, and histograms.
+ *
+ * Provides three metric types:
+ * - **Counters**: Monotonically increasing values (e.g., request count)
+ * - **Gauges**: Point-in-time values (e.g., memory usage)
+ * - **Histograms**: Distribution of values (e.g., latency)
+ *
+ * @example
+ * ```typescript
+ * const metrics = createMetricsCollector()
+ * metrics.increment('postgres.query.count', 1, { operation: 'SELECT' })
+ * metrics.gauge('postgres.memory.heap_bytes', heapUsage)
+ * metrics.histogram('postgres.query.duration_ms', durationMs)
+ * ```
+ */
+export interface MetricsCollector {
+    /** Increment a counter */
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    /** Record a gauge value */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /** Record a histogram value */
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    /** Get current metrics */
+    getMetrics(): MetricSnapshot[];
+    /** Reset all metrics */
+    reset(): void;
+}
+/**
+ * Metric snapshot
+ */
+export interface MetricSnapshot {
+    name: string;
+    type: 'counter' | 'gauge' | 'histogram';
+    value: number;
+    tags: Record<string, string>;
+    timestamp: number;
+}
+/**
+ * Observability context for request propagation
+ */
+export interface ObservabilityContext {
+    /** Current tracer */
+    tracer: Tracer;
+    /** Current metrics collector */
+    metrics: MetricsCollector;
+    /** Current span context (if any) */
+    currentSpan?: SpanContext | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"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"}

package/dist/observability/types.js

@@ -0,0 +1,103 @@
+/**
+ * @module observability/types
+ *
+ * Type definitions for the OpenTelemetry-compatible observability layer.
+ * Follows standard OTel patterns adapted for Cloudflare Workers.
+ *
+ * ## Core Concepts
+ *
+ * - **Spans**: Represent a single operation within a trace. Each span has a name,
+ *   start/end time, attributes, events, and status.
+ * - **Traces**: A collection of spans that share a common trace ID, representing
+ *   an end-to-end request flow.
+ * - **Metrics**: Numerical measurements like counters, gauges, and histograms.
+ * - **Context**: Propagated state (trace ID, span ID) that links operations together.
+ *
+ * ## Memory Considerations for Cloudflare Workers
+ *
+ * All types are designed to minimize memory allocation within the 128MB Worker limit:
+ * - Use primitive types where possible
+ * - Avoid deep nesting in attribute values
+ * - Span events and links are optional to reduce memory when not needed
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import type { Span, SpanContext, SpanAttributes } from '@dotdo/postgres/observability'
+ * import { SpanStatusCode, SpanKind } from '@dotdo/postgres/observability'
+ *
+ * // Type-safe span attributes
+ * const attributes: SpanAttributes = {
+ *   'db.system': 'postgresql',
+ *   'db.statement': 'SELECT * FROM users',
+ *   'db.rows_returned': 10,
+ * }
+ *
+ * // Span context for distributed tracing
+ * const context: SpanContext = {
+ *   traceId: '0af7651916cd43dd8448eb211c80319c',
+ *   spanId: 'b7ad6b7169203331',
+ *   traceFlags: 1, // Sampled
+ * }
+ * ```
+ */
+/**
+ * Span status codes following OpenTelemetry conventions.
+ *
+ * Used to indicate the outcome of a span's operation:
+ * - `OK`: Operation completed successfully
+ * - `UNSET`: Status not set (default for new spans)
+ * - `ERROR`: Operation failed with an error
+ *
+ * @example
+ * ```typescript
+ * span.setStatus({ code: SpanStatusCode.OK })
+ * span.setStatus({ code: SpanStatusCode.ERROR, message: 'Query timeout' })
+ * ```
+ */
+export var SpanStatusCode;
+(function (SpanStatusCode) {
+    /** The operation completed without errors */
+    SpanStatusCode[SpanStatusCode["OK"] = 0] = "OK";
+    /** The operation was not executed */
+    SpanStatusCode[SpanStatusCode["UNSET"] = 1] = "UNSET";
+    /** The operation contained an error */
+    SpanStatusCode[SpanStatusCode["ERROR"] = 2] = "ERROR";
+})(SpanStatusCode || (SpanStatusCode = {}));
+/**
+ * Span kind following OpenTelemetry conventions.
+ *
+ * Indicates the relationship between the span and its parent:
+ * - `INTERNAL`: Default kind for internal operations
+ * - `SERVER`: Handling an incoming request (e.g., HTTP server, RPC handler)
+ * - `CLIENT`: Initiating an outgoing request (e.g., database query, HTTP client)
+ * - `PRODUCER`: Creating a message for async processing
+ * - `CONSUMER`: Processing a message from a queue
+ *
+ * For postgres.do operations:
+ * - Use `CLIENT` for database queries
+ * - Use `SERVER` for Durable Object fetch handlers
+ * - Use `INTERNAL` for cache operations and internal processing
+ *
+ * @example
+ * ```typescript
+ * // Database query span
+ * const span = tracer.startSpan('postgres.query', {
+ *   kind: SpanKind.CLIENT,
+ *   attributes: { 'db.system': 'postgresql' },
+ * })
+ * ```
+ */
+export var SpanKind;
+(function (SpanKind) {
+    /** Default span kind - internal operation */
+    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
+    /** Server-side handling of an incoming request */
+    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
+    /** Client-side operation initiating a request */
+    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
+    /** Producer of a message */
+    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
+    /** Consumer of a message */
+    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
+})(SpanKind || (SpanKind = {}));
+//# sourceMappingURL=types.js.map

package/dist/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAN,IAAY,cAOX;AAPD,WAAY,cAAc;IACxB,6CAA6C;IAC7C,+CAAM,CAAA;IACN,qCAAqC;IACrC,qDAAS,CAAA;IACT,uCAAuC;IACvC,qDAAS,CAAA;AACX,CAAC,EAPW,cAAc,KAAd,cAAc,QAOzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAN,IAAY,QAWX;AAXD,WAAY,QAAQ;IAClB,6CAA6C;IAC7C,+CAAY,CAAA;IACZ,kDAAkD;IAClD,2CAAU,CAAA;IACV,iDAAiD;IACjD,2CAAU,CAAA;IACV,4BAA4B;IAC5B,+CAAY,CAAA;IACZ,4BAA4B;IAC5B,+CAAY,CAAA;AACd,CAAC,EAXW,QAAQ,KAAR,QAAQ,QAWnB"}

package/dist/pglite/workers-pglite.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Workers-Compatible PGLite Wrapper
+ *
+ * This module provides a production-grade PGLite implementation for Cloudflare Workers
+ * that works around the `addFunction` limitation by using the trampoline-based
+ * implementation from @dotdo/pglite/workers.
+ *
+ * Key features:
+ * - Uses pre-compiled WASM modules (no runtime compilation)
+ * - Uses EM_JS trampolines instead of addFunction (no CSP violations)
+ * - Properly handles fsBundle as ArrayBuffer or Blob
+ * - Provides query/exec/transaction interface compatible with PostgresDO
+ *
+ * @example
+ * ```typescript
+ * import { createWorkersPGLite } from './workers-pglite'
+ * import pgliteWasm from '../pglite-assets/pglite.wasm'
+ * import pgliteData from '../pglite-assets/pglite.data'
+ *
+ * const db = await createWorkersPGLite({
+ *   wasmModule: pgliteWasm,
+ *   fsBundle: pgliteData,
+ *   debug: true,
+ * })
+ *
+ * const result = await db.query('SELECT 1 + 1 AS sum')
+ * console.log(result.rows[0].sum) // 2
+ * ```
+ */
+import { type PGliteOptions, type DebugLevel } from '@dotdo/pglite';
+type PGliteWorkersOptions = PGliteOptions;
+type QueryResult<T = unknown> = {
+    rows: T[];
+    fields: {
+        name: string;
+        dataTypeID: number;
+    }[];
+    affectedRows?: number;
+};
+export type { DebugLevel };
+/**
+ * Configuration options for Workers PGLite
+ */
+export interface WorkersPGLiteOptions {
+    /**
+     * Pre-compiled WASM module
+     * Import this at bundle time: import pgliteWasm from './pglite.wasm'
+     */
+    wasmModule: WebAssembly.Module;
+    /**
+     * Filesystem bundle (pglite.data)
+     * Can be ArrayBuffer, Blob, ReadableStream, or typed array (Uint8Array)
+     * Import at bundle time: import pgliteData from './pglite.data'
+     */
+    fsBundle: ArrayBuffer | Blob | ReadableStream<Uint8Array> | ArrayBufferView;
+    /**
+     * Database name (default: 'postgres')
+     */
+    database?: string;
+    /**
+     * Enable debug logging (0-5 levels)
+     */
+    debug?: DebugLevel;
+    /**
+     * Extensions to load (for future extension support)
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * PGLite-compatible interface for use in PostgresDO
+ * Matches the PGliteLike interface expected by do.ts
+ */
+export interface WorkersPGLiteLike {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        fields: {
+            name: string;
+            dataTypeID: number;
+        }[];
+        affectedRows?: number;
+    }>;
+    exec?(sql: string): Promise<void>;
+    close?(): Promise<void>;
+    waitReady?: Promise<void>;
+    ready?: boolean;
+}
+/**
+ * Wrapper around PGliteWorkers that provides a compatible interface
+ * for PostgresDO and handles fsBundle conversion
+ */
+export declare class WorkersPGLite implements WorkersPGLiteLike {
+    private pglite;
+    private _ready;
+    private constructor();
+    /**
+     * Create a new WorkersPGLite instance
+     */
+    static create(options: WorkersPGLiteOptions): Promise<WorkersPGLite>;
+    /**
+     * Check if the database is ready
+     */
+    get ready(): boolean;
+    /**
+     * Promise that resolves when database is ready
+     * (already resolved for this implementation)
+     */
+    get waitReady(): Promise<void>;
+    /**
+     * Execute a SQL query with optional parameters
+     * Uses PGlite's native parameterized query support for SQL injection safety
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        fields: {
+            name: string;
+            dataTypeID: number;
+        }[];
+        affectedRows?: number;
+    }>;
+    /**
+     * Execute SQL without returning results
+     */
+    exec(sql: string): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+}
+/**
+ * Factory function to create a WorkersPGLite instance
+ */
+export declare function createWorkersPGLite(options: WorkersPGLiteOptions): Promise<WorkersPGLite>;
+/**
+ * Type guard to check if a value is a WorkersPGLite instance
+ */
+export declare function isWorkersPGLite(value: unknown): value is WorkersPGLite;
+export type { PGliteWorkersOptions, QueryResult };
+//# sourceMappingURL=workers-pglite.d.ts.map

package/dist/pglite/workers-pglite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-pglite.d.ts","sourceRoot":"","sources":["../../src/pglite/workers-pglite.ts"],"names":[],"mappings":"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"}