cooper-stack 0.1.0

package/src/cache.ts

@@ -0,0 +1,86 @@
+export interface CacheConfig {
+  ttl?: string; // e.g. "10m", "1h", "30s"
+}
+
+export interface CacheClient<T> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T, opts?: { ttl?: string }): Promise<void>;
+  getOrSet(key: string, factory: () => Promise<T>, opts?: { ttl?: string }): Promise<T>;
+  delete(key: string): Promise<void>;
+  invalidatePrefix(prefix: string): Promise<void>;
+  increment(key: string, opts?: { ttl?: string }): Promise<number>;
+}
+
+function parseTTL(ttl: string): number {
+  const match = ttl.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return 600;
+  const [, num, unit] = match;
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  return parseInt(num) * (multipliers[unit] ?? 60);
+}
+
+/**
+ * Declare a typed cache.
+ *
+ * ```ts
+ * export const userCache = cache<User>("users", { ttl: "10m" });
+ * const user = await userCache.getOrSet(userId, () => db.queryRow(...));
+ * ```
+ */
+export function cache<T = any>(name: string, config?: CacheConfig): CacheClient<T> {
+  const defaultTTL = config?.ttl ?? "10m";
+  let redis: any = null;
+
+  const ensureRedis = async () => {
+    if (redis) return redis;
+    const Redis = (await import("ioredis")).default;
+    const url = process.env.COOPER_VALKEY_URL ?? "redis://localhost:6379";
+    redis = new Redis(url);
+    return redis;
+  };
+
+  const prefixed = (key: string) => `cooper:${name}:${key}`;
+
+  return {
+    async get(key: string): Promise<T | null> {
+      const r = await ensureRedis();
+      const val = await r.get(prefixed(key));
+      return val ? JSON.parse(val) : null;
+    },
+
+    async set(key: string, value: T, opts?: { ttl?: string }): Promise<void> {
+      const r = await ensureRedis();
+      const ttlSec = parseTTL(opts?.ttl ?? defaultTTL);
+      await r.setex(prefixed(key), ttlSec, JSON.stringify(value));
+    },
+
+    async getOrSet(key: string, factory: () => Promise<T>, opts?: { ttl?: string }): Promise<T> {
+      const existing = await this.get(key);
+      if (existing !== null) return existing;
+      const value = await factory();
+      await this.set(key, value, opts);
+      return value;
+    },
+
+    async delete(key: string): Promise<void> {
+      const r = await ensureRedis();
+      await r.del(prefixed(key));
+    },
+
+    async invalidatePrefix(prefix: string): Promise<void> {
+      const r = await ensureRedis();
+      const keys = await r.keys(prefixed(prefix) + "*");
+      if (keys.length > 0) await r.del(...keys);
+    },
+
+    async increment(key: string, opts?: { ttl?: string }): Promise<number> {
+      const r = await ensureRedis();
+      const k = prefixed(key);
+      const val = await r.incr(k);
+      if (val === 1 && opts?.ttl) {
+        await r.expire(k, parseTTL(opts.ttl));
+      }
+      return val;
+    },
+  };
+}

package/src/cron.ts

@@ -0,0 +1,32 @@
+import { registry } from "./registry.js";
+
+export interface CronConfig {
+  schedule: string;
+  handler: () => Promise<void>;
+}
+
+/**
+ * Declare a cron job.
+ *
+ * ```ts
+ * export const cleanup = cron("cleanup", {
+ *   schedule: "every 1 hour",
+ *   handler: async () => {
+ *     await db.query("DELETE FROM sessions WHERE expires_at < NOW()");
+ *   },
+ * });
+ * ```
+ */
+export function cron(name: string, config: CronConfig) {
+  registry.registerCron(name, {
+    name,
+    schedule: config.schedule,
+    handler: config.handler,
+  });
+
+  return {
+    _cooper_type: "cron" as const,
+    name,
+    schedule: config.schedule,
+  };
+}

package/src/db.ts

@@ -0,0 +1,211 @@
+import { registry } from "./registry.js";
+
+export interface DatabaseConfig {
+  engine?: "postgres" | "mysql" | "mongodb" | "dynamodb";
+  migrations?: string;
+  partitionKey?: string;
+  sortKey?: string;
+}
+
+export interface TransactionClient {
+  /** Run a query returning multiple rows */
+  query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  /** Run a query returning a single row or null */
+  queryRow<T = any>(sql: string, params?: any[]): Promise<T | null>;
+  /** Run a query returning affected row count */
+  exec(sql: string, params?: any[]): Promise<{ rowCount: number }>;
+  /** Insert and return the inserted row */
+  insert<T = any>(table: string, data: Record<string, any>): Promise<T>;
+  /** Access the underlying connection (single client, not pool) */
+  conn: any;
+}
+
+export interface DatabaseClient {
+  /** Run a query returning multiple rows */
+  query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  /** Run a query returning a single row or null */
+  queryRow<T = any>(sql: string, params?: any[]): Promise<T | null>;
+  /** Run a query returning affected row count */
+  exec(sql: string, params?: any[]): Promise<{ rowCount: number }>;
+  /** Insert and return the inserted row */
+  insert<T = any>(table: string, data: Record<string, any>): Promise<T>;
+  /** Run a callback inside a transaction — auto-commits on success, rolls back on error */
+  transaction<R = any>(fn: (tx: TransactionClient) => Promise<R>): Promise<R>;
+  /** Access the underlying connection pool (for ORMs like Drizzle) */
+  pool: any;
+}
+
+/**
+ * Declare a database.
+ *
+ * ```ts
+ * export const db = database("main", { migrations: "./migrations" });
+ * const user = await db.queryRow<User>("SELECT * FROM users WHERE id = $1", [id]);
+ * ```
+ */
+export function database(name: string, config?: DatabaseConfig): DatabaseClient {
+  const engine = config?.engine ?? "postgres";
+
+  // Connection details injected by the Rust runtime via env vars
+  const connStr = process.env[`COOPER_DB_${name.toUpperCase()}_URL`]
+    ?? `postgres://cooper:cooper@localhost:5432/cooper_${name}`;
+
+  let pool: any = null;
+
+  const ensurePool = async () => {
+    if (pool) return pool;
+
+    if (engine === "postgres") {
+      const pg = await import("pg");
+      pool = new pg.default.Pool({ connectionString: connStr });
+      return pool;
+    }
+
+    if (engine === "mysql") {
+      const mysql = await import("mysql2/promise");
+      pool = await mysql.createPool(connStr);
+      return pool;
+    }
+
+    throw new Error(`Database engine "${engine}" not yet supported in JS runtime`);
+  };
+
+  const client: DatabaseClient = {
+    async query<T = any>(sql: string, params?: any[]): Promise<T[]> {
+      const p = await ensurePool();
+      if (engine === "postgres") {
+        const res = await p.query(sql, params);
+        return res.rows as T[];
+      }
+      if (engine === "mysql") {
+        const [rows] = await p.execute(sql, params);
+        return rows as T[];
+      }
+      return [];
+    },
+
+    async queryRow<T = any>(sql: string, params?: any[]): Promise<T | null> {
+      const rows = await client.query<T>(sql, params);
+      return rows[0] ?? null;
+    },
+
+    async exec(sql: string, params?: any[]): Promise<{ rowCount: number }> {
+      const p = await ensurePool();
+      if (engine === "postgres") {
+        const res = await p.query(sql, params);
+        return { rowCount: res.rowCount ?? 0 };
+      }
+      if (engine === "mysql") {
+        const [result] = await p.execute(sql, params);
+        return { rowCount: (result as any).affectedRows ?? 0 };
+      }
+      return { rowCount: 0 };
+    },
+
+    async insert<T = any>(table: string, data: Record<string, any>): Promise<T> {
+      const keys = Object.keys(data);
+      const values = Object.values(data);
+      const placeholders = keys.map((_, i) =>
+        engine === "postgres" ? `$${i + 1}` : "?"
+      );
+      const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders.join(", ")}) RETURNING *`;
+      const row = await client.queryRow<T>(sql, values);
+      return row!;
+    },
+
+    async transaction<R = any>(fn: (tx: TransactionClient) => Promise<R>): Promise<R> {
+      const p = await ensurePool();
+
+      if (engine === "postgres") {
+        const pgClient = await p.connect();
+        try {
+          await pgClient.query("BEGIN");
+
+          const tx: TransactionClient = {
+            async query<T = any>(sql: string, params?: any[]): Promise<T[]> {
+              const res = await pgClient.query(sql, params);
+              return res.rows as T[];
+            },
+            async queryRow<T = any>(sql: string, params?: any[]): Promise<T | null> {
+              const res = await pgClient.query(sql, params);
+              return (res.rows[0] as T) ?? null;
+            },
+            async exec(sql: string, params?: any[]): Promise<{ rowCount: number }> {
+              const res = await pgClient.query(sql, params);
+              return { rowCount: res.rowCount ?? 0 };
+            },
+            async insert<T = any>(table: string, data: Record<string, any>): Promise<T> {
+              const keys = Object.keys(data);
+              const values = Object.values(data);
+              const placeholders = keys.map((_, i) => `$${i + 1}`);
+              const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders.join(", ")}) RETURNING *`;
+              const res = await pgClient.query(sql, values);
+              return res.rows[0] as T;
+            },
+            get conn() { return pgClient; },
+          };
+
+          const result = await fn(tx);
+          await pgClient.query("COMMIT");
+          return result;
+        } catch (err) {
+          await pgClient.query("ROLLBACK");
+          throw err;
+        } finally {
+          pgClient.release();
+        }
+      }
+
+      if (engine === "mysql") {
+        const conn = await p.getConnection();
+        try {
+          await conn.beginTransaction();
+
+          const tx: TransactionClient = {
+            async query<T = any>(sql: string, params?: any[]): Promise<T[]> {
+              const [rows] = await conn.execute(sql, params);
+              return rows as T[];
+            },
+            async queryRow<T = any>(sql: string, params?: any[]): Promise<T | null> {
+              const [rows] = await conn.execute(sql, params);
+              return ((rows as any[])[0] as T) ?? null;
+            },
+            async exec(sql: string, params?: any[]): Promise<{ rowCount: number }> {
+              const [result] = await conn.execute(sql, params);
+              return { rowCount: (result as any).affectedRows ?? 0 };
+            },
+            async insert<T = any>(table: string, data: Record<string, any>): Promise<T> {
+              const keys = Object.keys(data);
+              const values = Object.values(data);
+              const placeholders = keys.map(() => "?");
+              const sql = `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders.join(", ")})`;
+              await conn.execute(sql, values);
+              const [rows] = await conn.execute(`SELECT * FROM ${table} WHERE id = LAST_INSERT_ID()`);
+              return (rows as any[])[0] as T;
+            },
+            get conn() { return conn; },
+          };
+
+          const result = await fn(tx);
+          await conn.commit();
+          return result;
+        } catch (err) {
+          await conn.rollback();
+          throw err;
+        } finally {
+          conn.release();
+        }
+      }
+
+      throw new Error(`Transactions not supported for engine "${engine}"`);
+    },
+
+    get pool() {
+      return pool;
+    },
+  };
+
+  registry.registerDatabase(name, { name, engine, pool: client });
+
+  return client;
+}

package/src/error.ts

@@ -0,0 +1,44 @@
+/**
+ * Structured error codes with automatic HTTP status mapping.
+ */
+export type ErrorCode =
+  | "NOT_FOUND"
+  | "UNAUTHORIZED"
+  | "PERMISSION_DENIED"
+  | "RATE_LIMITED"
+  | "INVALID_ARGUMENT"
+  | "VALIDATION_FAILED"
+  | "INTERNAL";
+
+const STATUS_MAP: Record<ErrorCode, number> = {
+  NOT_FOUND: 404,
+  UNAUTHORIZED: 401,
+  PERMISSION_DENIED: 403,
+  RATE_LIMITED: 429,
+  INVALID_ARGUMENT: 400,
+  VALIDATION_FAILED: 422,
+  INTERNAL: 500,
+};
+
+export class CooperError extends Error {
+  public readonly code: ErrorCode;
+  public readonly statusCode: number;
+  public retryAfter?: number;
+
+  constructor(code: ErrorCode, message: string) {
+    super(message);
+    this.name = "CooperError";
+    this.code = code;
+    this.statusCode = STATUS_MAP[code] ?? 500;
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.retryAfter !== undefined && { retryAfter: this.retryAfter }),
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { api } from "./api.js";
+export { CooperError, type ErrorCode } from "./error.js";
+export { database, type DatabaseClient, type TransactionClient } from "./db.js";
+export { middleware, cooper } from "./middleware.js";
+export { authHandler } from "./auth.js";
+export { topic, type Topic } from "./pubsub.js";
+export { closeNats } from "./nats.js";
+export { cron } from "./cron.js";
+export { cache, type CacheClient } from "./cache.js";
+export { bucket, type BucketClient } from "./storage.js";
+export { secret } from "./secrets.js";
+export { queue, type QueueClient } from "./queue.js";
+export { page, layout, pageLoader, Suspense } from "./ssr.js";
+export { island } from "./islands.js";
+export { vectorStore, llmGateway } from "./ai.js";
+export { rateLimit, type RateLimitConfig } from "./rateLimit.js";
+export { registry } from "./registry.js";

package/src/islands.ts

@@ -0,0 +1,28 @@
+export type HydrationStrategy = "load" | "visible" | "idle" | "interaction" | "none";
+
+/**
+ * Mark a component as an island — it will be hydrated on the client.
+ *
+ * ```tsx
+ * // islands/LikeButton.island.tsx
+ * export default island(function LikeButton({ userId, initialCount }) {
+ *   const [count, setCount] = useState(initialCount);
+ *   return <button onClick={...}>Like ({count})</button>;
+ * });
+ * ```
+ */
+export function island<P = any>(
+  component: (props: P) => any
+): (props: P & { hydrate?: HydrationStrategy }) => any {
+  // Mark the component for the bundler
+  const wrapper = (props: P & { hydrate?: HydrationStrategy }) => {
+    // Server-side: render the component to HTML
+    // Client-side: hydrate based on strategy
+    return component(props);
+  };
+
+  (wrapper as any)._cooper_island = true;
+  (wrapper as any)._cooper_hydrate = "load"; // default strategy
+
+  return wrapper;
+}

package/src/middleware.ts

@@ -0,0 +1,27 @@
+import { registry, type MiddlewareFn } from "./registry.js";
+
+/**
+ * Define a middleware function.
+ *
+ * ```ts
+ * const rateLimiter = middleware(async (req, next) => {
+ *   const count = await userCache.increment(`rate:${req.ip}`, { ttl: "1m" });
+ *   if (count > 100) throw new CooperError("RATE_LIMITED");
+ *   return next(req);
+ * });
+ * ```
+ */
+export function middleware(fn: MiddlewareFn): MiddlewareFn {
+  return fn;
+}
+
+/**
+ * Cooper instance for global middleware registration.
+ */
+export const cooper = {
+  use(...middlewares: MiddlewareFn[]) {
+    for (const mw of middlewares) {
+      registry.addGlobalMiddleware(mw);
+    }
+  },
+};

package/src/nats.ts

@@ -0,0 +1,186 @@
+/**
+ * NATS Connection Manager — singleton lazy connection to embedded NATS.
+ *
+ * JetStream is used for durable pub/sub with delivery guarantees.
+ * Falls back gracefully if NATS is unavailable (logs warning once).
+ */
+
+import {
+  connect,
+  type NatsConnection,
+  type JetStreamClient,
+  type JetStreamManager,
+  JSONCodec,
+  RetentionPolicy,
+  StorageType,
+  AckPolicy,
+} from "nats";
+
+let nc: NatsConnection | null = null;
+let js: JetStreamClient | null = null;
+let jsm: JetStreamManager | null = null;
+let connectPromise: Promise<boolean> | null = null;
+let warnedOnce = false;
+
+const jc = JSONCodec();
+
+function getNatsUrl(): string {
+  return process.env.COOPER_NATS_URL ?? "nats://localhost:4222";
+}
+
+async function doConnect(): Promise<boolean> {
+  try {
+    nc = await connect({ servers: getNatsUrl(), maxReconnectAttempts: 5 });
+    js = nc.jetstream();
+    jsm = await nc.jetstreamManager();
+    return true;
+  } catch (err: any) {
+    if (!warnedOnce) {
+      console.warn(
+        `[cooper] NATS unavailable at ${getNatsUrl()} — pub/sub will use in-memory fallback. ${err.message}`
+      );
+      warnedOnce = true;
+    }
+    nc = null;
+    js = null;
+    jsm = null;
+    return false;
+  }
+}
+
+export async function ensureConnected(): Promise<boolean> {
+  if (nc && !nc.isClosed()) return true;
+  if (connectPromise) return connectPromise;
+  connectPromise = doConnect().finally(() => {
+    connectPromise = null;
+  });
+  return connectPromise;
+}
+
+export function getJetStream(): JetStreamClient | null {
+  return js;
+}
+
+export function getJetStreamManager(): JetStreamManager | null {
+  return jsm;
+}
+
+export function getConnection(): NatsConnection | null {
+  return nc;
+}
+
+export { jc as jsonCodec };
+
+/**
+ * Sanitize a topic name into a valid NATS stream name.
+ * NATS streams: alphanumeric + dash + underscore only.
+ */
+export function streamName(topicName: string): string {
+  return "COOPER_" + topicName.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+}
+
+/**
+ * Sanitize a subscriber name into a valid NATS durable consumer name.
+ */
+export function consumerName(subscriberName: string): string {
+  return subscriberName.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Ensure a JetStream stream exists for a topic.
+ * Creates it if missing, no-ops if it already exists.
+ */
+export async function ensureStream(
+  topicName: string,
+  config?: { dedup?: boolean }
+): Promise<void> {
+  if (!jsm) return;
+
+  const name = streamName(topicName);
+  const subject = `cooper.topic.${topicName}`;
+
+  try {
+    await jsm.streams.info(name);
+  } catch {
+    await jsm.streams.add({
+      name,
+      subjects: [subject],
+      retention: RetentionPolicy.Interest,
+      max_msgs: -1,
+      max_bytes: -1,
+      max_age: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days in nanos
+      storage: StorageType.File,
+      num_replicas: 1,
+      duplicate_window: config?.dedup
+        ? 2 * 60 * 1_000_000_000 // 2 min dedup window
+        : 0,
+    });
+  }
+}
+
+/**
+ * Ensure a JetStream stream exists for a job queue.
+ * Uses WorkQueue retention — each message consumed by exactly one worker.
+ */
+export async function ensureQueueStream(
+  queueName: string,
+  config?: { dedup?: boolean }
+): Promise<void> {
+  if (!jsm) return;
+
+  const name = "QUEUE_" + queueName.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+  const subject = `cooper.queue.${queueName}`;
+
+  try {
+    await jsm.streams.info(name);
+  } catch {
+    await jsm.streams.add({
+      name,
+      subjects: [subject],
+      retention: RetentionPolicy.Workqueue,
+      max_msgs: -1,
+      max_bytes: -1,
+      max_age: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days in nanos
+      storage: StorageType.File,
+      num_replicas: 1,
+      duplicate_window: config?.dedup
+        ? 5 * 60 * 1_000_000_000 // 5 min dedup window for queues
+        : 0,
+    });
+  }
+}
+
+/**
+ * Ensure a JetStream stream exists for a dead-letter queue.
+ * Uses Limits retention — messages stay until explicitly purged.
+ */
+export async function ensureDLQStream(dlqName: string): Promise<void> {
+  if (!jsm) return;
+
+  const name = "DLQ_" + dlqName.replace(/[^a-zA-Z0-9_-]/g, "_").toUpperCase();
+  const subject = `cooper.dlq.${dlqName}`;
+
+  try {
+    await jsm.streams.info(name);
+  } catch {
+    await jsm.streams.add({
+      name,
+      subjects: [subject],
+      retention: RetentionPolicy.Limits,
+      max_msgs: 10000,
+      max_bytes: -1,
+      max_age: 30 * 24 * 60 * 60 * 1_000_000_000, // 30 days
+      storage: StorageType.File,
+      num_replicas: 1,
+    });
+  }
+}
+
+/**
+ * Graceful shutdown — drain and close the connection.
+ */
+export async function closeNats(): Promise<void> {
+  if (nc && !nc.isClosed()) {
+    await nc.drain();
+  }
+}