@alfredmouelle/create-stack 0.1.1 → 0.2.0

package/_stack/packages/cache/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@alfredmouelle/cache",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ioredis": "^5.11.1",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/cache/src/adapters/memory/index.ts

@@ -0,0 +1,51 @@
+import type { CachePort } from '../../core/port.js'
+import { wrapValue } from '../../core/wrap.js'
+
+interface Entry {
+  value: unknown
+  /** Epoch ms expiry; `undefined` = no expiry. */
+  expiresAt?: number
+}
+
+export interface MemoryAdapterOptions {
+  /** Seed store (mostly for tests). */
+  store?: Map<string, Entry>
+}
+
+/** In-process `Map` cache with lazy per-key expiry; no deps. Dev/tests. */
+export function memoryAdapter(options: MemoryAdapterOptions = {}): CachePort {
+  const store = options.store ?? new Map<string, Entry>()
+
+  function read(key: string): Entry | null {
+    const entry = store.get(key)
+    if (entry === undefined) return null
+    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+      store.delete(key)
+      return null
+    }
+    return entry
+  }
+
+  const port: CachePort = {
+    name: 'memory',
+    async get<T>(key: string) {
+      const entry = read(key)
+      return entry === null ? null : (entry.value as T)
+    },
+    async set<T>(key: string, value: T, ttlSeconds?: number) {
+      const expiresAt = ttlSeconds === undefined ? undefined : Date.now() + ttlSeconds * 1000
+      store.set(key, { value, expiresAt })
+    },
+    async delete(key: string) {
+      store.delete(key)
+    },
+    async has(key: string) {
+      return read(key) !== null
+    },
+    wrap<T>(key: string, factory: () => Promise<T>, ttlSeconds?: number) {
+      return wrapValue(port, key, factory, ttlSeconds)
+    },
+  }
+
+  return port
+}

package/_stack/packages/cache/src/adapters/redis/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const RedisConfigSchema = v.object({
+  url: v.optional(v.string()),
+  keyPrefix: v.optional(v.string()),
+})
+
+export type RedisConfig = v.InferOutput<typeof RedisConfigSchema>

package/_stack/packages/cache/src/adapters/redis/index.ts

@@ -0,0 +1,73 @@
+import { Redis } from 'ioredis'
+import * as v from 'valibot'
+import { CacheError, type CachePort } from '../../core/port.js'
+import { wrapValue } from '../../core/wrap.js'
+import { RedisConfigSchema } from './config.js'
+
+/** Minimal structural view of the Redis client (eases testing). */
+export interface RedisLike {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, secondsToken?: 'EX', seconds?: number): Promise<unknown>
+  del(key: string): Promise<unknown>
+  exists(key: string): Promise<number>
+}
+
+export interface RedisAdapterOptions {
+  /** Inject a custom/mock client; defaults to a real `Redis`. */
+  client?: RedisLike
+  /** Connection URL when no `client` is injected. */
+  url?: string
+  /** Prepended to every key. */
+  keyPrefix?: string
+}
+
+export function redisAdapter(options: RedisAdapterOptions = {}): CachePort {
+  // Validate early: bad option fails at construction, not at use.
+  const config = v.parse(RedisConfigSchema, { url: options.url, keyPrefix: options.keyPrefix })
+  const defaultClient = () =>
+    (config.url ? new Redis(config.url) : new Redis()) as unknown as RedisLike
+  const client: RedisLike = options.client ?? defaultClient()
+  const prefix = config.keyPrefix ?? ''
+  const k = (key: string) => `${prefix}${key}`
+
+  const port: CachePort = {
+    name: 'redis',
+    async get<T>(key: string) {
+      try {
+        const raw = await client.get(k(key))
+        if (raw === null) return null
+        return JSON.parse(raw) as T
+      } catch (cause) {
+        throw new CacheError('Failed to read from Redis', { adapter: 'redis', cause })
+      }
+    },
+    async set<T>(key: string, value: T, ttlSeconds?: number) {
+      try {
+        const json = JSON.stringify(value)
+        if (ttlSeconds === undefined) await client.set(k(key), json)
+        else await client.set(k(key), json, 'EX', ttlSeconds)
+      } catch (cause) {
+        throw new CacheError('Failed to write to Redis', { adapter: 'redis', cause })
+      }
+    },
+    async delete(key: string) {
+      try {
+        await client.del(k(key))
+      } catch (cause) {
+        throw new CacheError('Failed to delete from Redis', { adapter: 'redis', cause })
+      }
+    },
+    async has(key: string) {
+      try {
+        return (await client.exists(k(key))) > 0
+      } catch (cause) {
+        throw new CacheError('Failed to query Redis', { adapter: 'redis', cause })
+      }
+    },
+    wrap<T>(key: string, factory: () => Promise<T>, ttlSeconds?: number) {
+      return wrapValue(port, key, factory, ttlSeconds)
+    },
+  }
+
+  return port
+}

package/_stack/packages/cache/src/core/port.ts

@@ -0,0 +1,29 @@
+/**
+ * App-facing port; swap adapters at the composition root, never this interface.
+ * Values are JSON-serialized for remote stores, so stored values must be JSON-serializable.
+ */
+export interface CachePort {
+  /** Backing adapter name (`redis`, `memory`, …). */
+  readonly name: string
+  /** Read a value, or `null` if absent/expired. */
+  get<T>(key: string): Promise<T | null>
+  /** Store a value, optionally expiring after `ttlSeconds`. */
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>
+  /** Remove a key (no-op if absent). */
+  delete(key: string): Promise<void>
+  /** Whether a non-expired value exists. */
+  has(key: string): Promise<boolean>
+  /** Read-through: cached value, else `factory()` stored with `ttlSeconds`. */
+  wrap<T>(key: string, factory: () => Promise<T>, ttlSeconds?: number): Promise<T>
+}
+
+/** Normalized adapter error; callers never catch backend types. */
+export class CacheError extends Error {
+  readonly adapter: string
+
+  constructor(message: string, options: { adapter: string; cause?: unknown }) {
+    super(message, { cause: options.cause })
+    this.name = 'CacheError'
+    this.adapter = options.adapter
+  }
+}

package/_stack/packages/cache/src/core/wrap.ts

@@ -0,0 +1,20 @@
+/** Minimal read/write pair `wrap` needs; adapters pass their own `get`/`set`. */
+export interface WrapStore {
+  get<T>(key: string): Promise<T | null>
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>
+}
+
+/** Read-through: return cached value, else call `factory()`, store with `ttlSeconds`, return. */
+export async function wrapValue<T>(
+  store: WrapStore,
+  key: string,
+  factory: () => Promise<T>,
+  ttlSeconds?: number,
+): Promise<T> {
+  const cached = await store.get<T>(key)
+  if (cached !== null) return cached
+
+  const value = await factory()
+  await store.set(key, value, ttlSeconds)
+  return value
+}

package/_stack/packages/cache/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  type MemoryAdapterOptions,
+  memoryAdapter,
+} from './adapters/memory/index.js'
+export { type RedisConfig, RedisConfigSchema } from './adapters/redis/config.js'
+export {
+  type RedisAdapterOptions,
+  type RedisLike,
+  redisAdapter,
+} from './adapters/redis/index.js'
+export type { CachePort } from './core/port.js'
+export { CacheError } from './core/port.js'

package/_stack/packages/error-tracking/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@alfredmouelle/error-tracking",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@sentry/node": "^10.59.0",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/error-tracking/src/adapters/console/index.ts

@@ -0,0 +1,43 @@
+import type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from '../../core/port.js'
+
+export interface ConsoleAdapterOptions {
+  /** Max breadcrumbs kept in memory (oldest dropped). Default 20. */
+  maxBreadcrumbs?: number
+}
+
+/** Dev/test adapter logging to console; user + breadcrumb state kept in-memory (no transport). */
+export function consoleAdapter(options: ConsoleAdapterOptions = {}): ErrorTrackingPort {
+  const maxBreadcrumbs = options.maxBreadcrumbs ?? 20
+  let user: ErrorUser | null = null
+  const breadcrumbs: Breadcrumb[] = []
+
+  function state() {
+    return { user, breadcrumbs }
+  }
+
+  return {
+    name: 'console',
+    captureException(error: unknown, context?: CaptureContext) {
+      console.error('[error-tracking] exception', error, { ...context, ...state() })
+    },
+    captureMessage(message: string, level: SeverityLevel = 'info') {
+      console.error('[error-tracking] message', { message, level, ...state() })
+    },
+    setUser(next: ErrorUser | null) {
+      user = next
+    },
+    addBreadcrumb(breadcrumb: Breadcrumb) {
+      breadcrumbs.push(breadcrumb)
+      if (breadcrumbs.length > maxBreadcrumbs) breadcrumbs.shift()
+    },
+    flush() {
+      return Promise.resolve(true)
+    },
+  }
+}

package/_stack/packages/error-tracking/src/adapters/sentry/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const SentryConfigSchema = v.object({
+  dsn: v.pipe(v.string(), v.minLength(1, 'SENTRY_DSN is required')),
+  environment: v.optional(v.string()),
+})
+
+export type SentryConfig = v.InferOutput<typeof SentryConfigSchema>

package/_stack/packages/error-tracking/src/adapters/sentry/index.ts

@@ -0,0 +1,72 @@
+import * as Sentry from '@sentry/node'
+import * as v from 'valibot'
+import type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from '../../core/port.js'
+import { SentryConfigSchema } from './config.js'
+
+/** Minimal structural view of the Sentry namespace (eases testing). */
+export interface SentryCaptureContext {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+  level?: SeverityLevel
+}
+
+export interface SentryLike {
+  init(options: { dsn: string; environment?: string }): void
+  captureException(error: unknown, context?: SentryCaptureContext): void
+  captureMessage(message: string, level?: SeverityLevel): void
+  setUser(user: ErrorUser | null): void
+  addBreadcrumb(breadcrumb: Breadcrumb): void
+  flush(timeoutMs?: number): Promise<boolean>
+}
+
+export interface SentryAdapterOptions {
+  dsn: string
+  environment?: string
+  /** Inject a custom/mock client; defaults to the real `@sentry/node`. */
+  client?: SentryLike
+  /** Skip the implicit `Sentry.init` (e.g. init happens elsewhere). */
+  init?: boolean
+}
+
+export function sentryAdapter(options: SentryAdapterOptions): ErrorTrackingPort {
+  // Validate early: missing DSN fails at construction, not at capture().
+  const config = v.parse(SentryConfigSchema, {
+    dsn: options.dsn,
+    environment: options.environment,
+  })
+  const client: SentryLike = options.client ?? (Sentry as unknown as SentryLike)
+
+  // Only init the real namespace; injected clients are assumed already wired.
+  if (options.init !== false && !options.client) {
+    client.init({ dsn: config.dsn, environment: config.environment })
+  }
+
+  return {
+    name: 'sentry',
+    captureException(error: unknown, context?: CaptureContext) {
+      client.captureException(error, {
+        tags: context?.tags,
+        extra: context?.extra,
+        level: context?.level,
+      })
+    },
+    captureMessage(message: string, level?: SeverityLevel) {
+      client.captureMessage(message, level)
+    },
+    setUser(user: ErrorUser | null) {
+      client.setUser(user)
+    },
+    addBreadcrumb(breadcrumb: Breadcrumb) {
+      client.addBreadcrumb(breadcrumb)
+    },
+    flush(timeoutMs?: number) {
+      return client.flush(timeoutMs)
+    },
+  }
+}

package/_stack/packages/error-tracking/src/core/port.ts

@@ -0,0 +1,39 @@
+/** Captured-event severity, matching common provider levels. */
+export type SeverityLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug'
+
+/** User an event is associated with. */
+export interface ErrorUser {
+  id?: string
+  email?: string
+  username?: string
+}
+
+/** Trail of events leading up to an error, for debugging. */
+export interface Breadcrumb {
+  message: string
+  category?: string
+  level?: SeverityLevel
+  data?: Record<string, unknown>
+}
+
+/** Extra context attached to a single capture. */
+export interface CaptureContext {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+  level?: SeverityLevel
+}
+
+/** App-facing port; swap adapters at the composition root, never this interface. */
+export interface ErrorTrackingPort {
+  readonly name: string
+  /** Report an error (or any thrown value) with optional context. */
+  captureException(error: unknown, context?: CaptureContext): void
+  /** Report a standalone message at severity (default `info`). */
+  captureMessage(message: string, level?: SeverityLevel): void
+  /** Associate subsequent events with a user; `null` clears. */
+  setUser(user: ErrorUser | null): void
+  /** Record a breadcrumb for subsequent events. */
+  addBreadcrumb(breadcrumb: Breadcrumb): void
+  /** Flush buffered events; resolves `true` if all sent in time. */
+  flush(timeoutMs?: number): Promise<boolean>
+}

package/_stack/packages/error-tracking/src/index.ts

@@ -0,0 +1,14 @@
+export { type ConsoleAdapterOptions, consoleAdapter } from './adapters/console/index.js'
+export { type SentryConfig, SentryConfigSchema } from './adapters/sentry/config.js'
+export {
+  type SentryAdapterOptions,
+  type SentryLike,
+  sentryAdapter,
+} from './adapters/sentry/index.js'
+export type {
+  Breadcrumb,
+  CaptureContext,
+  ErrorTrackingPort,
+  ErrorUser,
+  SeverityLevel,
+} from './core/port.js'

package/_stack/packages/http/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@alfredmouelle/http",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}