@prestack/thread 0.1.3 → 0.1.5

package/dist/operations/memory.ts

@@ -1,470 +0,0 @@
-import { randomUUID } from 'node:crypto'
-
-import type { Actor } from '../core/actor.ts'
-import type {
-  Store, Row, Seams, Telemetry, Log, Audit, Errors, Search, Cost, Idempotency, EventBus, RateLimiter, PlatformEvent, LogLevel,
-  Queue, Job, EnqueueOpts, Transactional, FeatureGate, Quotas, Outbox, AuditRecord, ErrorRecord, Vault,
-  Files, Views, FieldList } from './seams.ts'
-import { backoffMs, isExhausted } from './queue-policy.ts'
-
-function projectRow(row: Row, fields: FieldList, key: string): Row {
-  const keep = new Set<string>([key, 'version', ...fields])
-  const projected: Row = {}
-  for (const [name, value] of Object.entries(row)) {
-    if (keep.has(name)) projected[name] = value
-  }
-  return projected
-}
-
-export class UnknownColumnError extends Error {
-  constructor(entity: string, key: string) {
-    super(
-      `${entity} does not declare "${key}", so writing it would be silently discarded. ` +
-        'Declare the field or relation on the entity, or stop writing the key.',
-    )
-    this.name = 'UnknownColumnError'
-  }
-}
-
-export class VersionConflictError extends Error {
-  constructor(entity: string, id: string, expectedVersion: number) {
-    super(
-      `${entity} ${id} was not at version ${expectedVersion} — someone else changed it first. ` +
-        're-read the row and retry with its current ETag.',
-    )
-    this.name = 'VersionConflictError'
-  }
-}
-
-export class MemoryStore implements Store, Transactional {
-  private data = new Map<string, Row[]>()
-
-  private readonly declared: ReadonlyMap<string, ReadonlySet<string>>
-
-  private readonly keys: ReadonlyMap<string, string>
-
-  constructor(declared?: ReadonlyMap<string, ReadonlySet<string>>, keys?: ReadonlyMap<string, string>) {
-    this.declared = declared ?? new Map()
-    this.keys = keys ?? new Map()
-  }
-
-  private keyOf(entity: string): string {
-    const held = this.keys.get(entity)
-    if (held === undefined) {
-      throw new Error(
-        `nothing told this store which value identifies a ${entity}, so it cannot find one row rather than all of ` +
-          'them. An entity states that with a `unique` invariant over one of its values, and whatever builds this ' +
-          'store passes those along with the columns each entity declares.',
-      )
-    }
-    return held
-  }
-
-  private static readonly SYSTEM = new Set(['version'])
-
-  private assertDeclared(entity: string, row: Record<string, unknown>): void {
-    const allowed = this.declared.get(entity)
-    if (allowed === undefined) return
-    for (const key of Object.keys(row)) {
-      if (allowed.has(key) || MemoryStore.SYSTEM.has(key)) continue
-      throw new UnknownColumnError(entity, key)
-    }
-  }
-
-  private depth = 0
-
-  async transaction<T>(_actor: Actor, fn: () => Promise<T>): Promise<T> {
-    if (this.depth > 0) return fn()
-    const snapshot = new Map<string, Row[]>()
-    for (const [key, rows] of this.data) snapshot.set(key, rows.map((r) => ({ ...r })))
-
-    this.depth += 1
-    try {
-      return await fn()
-    } catch (err) {
-      this.data = snapshot
-      throw err
-    } finally {
-      this.depth -= 1
-    }
-  }
-
-  async insert(_actor: Actor, entity: string, row: Row): Promise<Row> {
-    this.assertDeclared(entity, row)
-    const rows = this.data.get(entity) ?? []
-
-    const rec = { ...row, version: 1 }
-    rows.push(rec)
-    this.data.set(entity, rows)
-    return { ...rec }
-  }
-
-  async get(_actor: Actor, entity: string, key: string | number, fields: FieldList): Promise<Row | null> {
-    const named = this.keyOf(entity)
-    const row = this.data.get(entity)?.find((r) => r[named] === key) ?? null
-    return row === null ? null : projectRow(row, fields, named)
-  }
-  async list(
-    _actor: Actor,
-    entity: string,
-    opts?: { limit?: number; where?: Readonly<Record<string, string | number | boolean | null>> },
-  ): Promise<Row[]> {
-    const all = this.data.get(entity) ?? []
-
-    const where = Object.entries(opts?.where ?? {})
-    for (const [field] of where) this.assertDeclared(entity, { [field]: null })
-
-    const matched = where.length === 0 ? all : all.filter((row) => where.every(([f, v]) => (row[f] ?? null) === v))
-    return opts?.limit ? matched.slice(0, opts.limit).map((r) => ({ ...r })) : matched.map((r) => ({ ...r }))
-  }
-  async update(
-    _actor: Actor,
-    entity: string,
-    key: string | number,
-    patch: Record<string, unknown>,
-    expectedVersion?: number,
-  ): Promise<Row> {
-    this.assertDeclared(entity, patch)
-    const named = this.keyOf(entity)
-    const rows = this.data.get(entity) ?? []
-    const i = rows.findIndex((r) => r[named] === key)
-    const cur = rows[i]
-    if (i < 0 || !cur) throw new Error(`record ${String(key)} not found`)
-    const currentVersion = typeof cur['version'] === 'number' ? cur['version'] : 1
-    if (expectedVersion !== undefined && expectedVersion !== currentVersion) {
-      throw new VersionConflictError(entity, String(key), expectedVersion)
-    }
-
-    const next = { ...cur, ...patch, [named]: key, version: currentVersion + 1 }
-    rows[i] = next
-    return { ...next }
-  }
-  async remove(_actor: Actor, entity: string, key: string | number): Promise<void> {
-    const named = this.keyOf(entity)
-    this.data.set(entity, (this.data.get(entity) ?? []).filter((r) => r[named] !== key))
-  }
-}
-
-export class MemoryQueue implements Queue {
-  private jobs = new Map<string, Job & { runAt: number; claimed: boolean; dedupeKey?: string }>()
-  private dead: Job[] = []
-  private seq = 0
-
-  async enqueue<T>(actor: Actor, kind: string, payload: T, opts?: EnqueueOpts): Promise<string> {
-
-    if (opts?.dedupeKey) {
-      for (const [id, job] of this.jobs) {
-        if (job.dedupeKey === opts.dedupeKey) return id
-      }
-    }
-    const id = `job_${++this.seq}`
-    this.jobs.set(id, {
-      id,
-      kind,
-      payload,
-      attempts: 0,
-      runAt: opts?.runAt ?? 0,
-      claimed: false,
-      dedupeKey: opts?.dedupeKey,
-      actor,
-    })
-    return id
-  }
-
-  async poll(kinds: string[], limit: number, now: number): Promise<Job[]> {
-    const due: Job[] = []
-    for (const job of this.jobs.values()) {
-      if (due.length >= limit) break
-      if (job.claimed || !kinds.includes(job.kind) || job.runAt > now) continue
-      job.claimed = true
-      due.push({ ...job })
-    }
-    return due
-  }
-
-  async ack(id: string): Promise<void> {
-    this.jobs.delete(id)
-  }
-
-  async fail(id: string, error: string, now: number): Promise<void> {
-    const job = this.jobs.get(id)
-    if (!job) return
-    job.attempts += 1
-    job.claimed = false
-
-    if (isExhausted(job.attempts)) {
-
-      this.dead.push({ ...job })
-      this.jobs.delete(id)
-      return
-    }
-    job.runAt = now + backoffMs(job.attempts)
-    void error
-  }
-
-  async deadLetter(id: string, error: string): Promise<void> {
-    const job = this.jobs.get(id)
-    if (!job) return
-    this.dead.push({ ...job })
-    this.jobs.delete(id)
-    void error
-  }
-
-  async deadLetters(): Promise<Job[]> {
-    return this.dead.map((j) => ({ ...j }))
-  }
-}
-
-export interface Sink {
-  logs: { level: LogLevel; action: string; data: Record<string, unknown> }[]
-  events: PlatformEvent[]
-  audits: AuditRecord[]
-  errors: ErrorRecord[]
-  costs: string[]
-  indexed: { entity: string; row: Row }[]
-  spans: { action: string; status: 'ok' | 'error' }[]
-
-  outbox: PlatformEvent[]
-
-  gateOrder: string[]
-
-  quota: { reserved: number[]; committed: number[]; released: number }
-
-  files: { action: 'put' | 'get' | 'signed' | 'remove'; key: string; bytes: number | null }[]
-
-  queries: { sql: string; params: readonly unknown[]; rows: number }[]
-}
-
-export class MemoryIdempotency implements Idempotency {
-  private readonly records: Map<string, unknown>
-  private readonly onCheck?: () => void
-
-  constructor(opts: {
-    readonly onCheck?: () => void
-
-    readonly records?: Map<string, unknown>
-  }) {
-    this.records = opts.records ?? new Map<string, unknown>()
-    this.onCheck = opts.onCheck
-  }
-
-  private keyFor(key: string, action: string): string {
-    return `${key}:${action}`
-  }
-
-  async check(key: string | undefined, action: string): Promise<unknown | null> {
-    this.onCheck?.()
-    if (!key) return null
-    const k = this.keyFor(key, action)
-    return this.records.has(k) ? (this.records.get(k) ?? null) : null
-  }
-
-  async store(key: string | undefined, action: string, output: unknown): Promise<void> {
-    if (!key) return
-    const k = this.keyFor(key, action)
-
-    if (!this.records.has(k)) this.records.set(k, output)
-  }
-}
-
-export interface MemorySeamOptions {
-  readonly allowRate?: boolean
-
-  readonly features?: readonly string[]
-
-  readonly quota?: Readonly<Record<string, number>>
-  readonly onExceed?: string
-
-  readonly entities?: ReadonlyMap<string, ReadonlySet<string>>
-
-  readonly keys?: ReadonlyMap<string, string>
-
-  readonly secrets?: Readonly<Record<string, string>>
-
-  readonly views?: Readonly<Record<string, readonly unknown[]>>
-}
-
-export function memoryVault(seed: Readonly<Record<string, string>> = {}): Vault {
-  return {
-    async resolve(refs) {
-      const found: Record<string, string> = {}
-      for (const ref of refs) {
-        const value = seed[ref]
-        if (value === undefined) throw new Error(`vault has no value for "${ref}"`)
-        found[ref] = value
-      }
-      return found
-    },
-  }
-}
-
-export const arrived = (): number => Date.now()
-
-export const fresh = (): string => randomUUID()
-
-export function inMemorySeams(opts?: MemorySeamOptions): {
-  seams: Seams
-  sink: Sink
-  store: MemoryStore
-  queue: MemoryQueue
-} {
-  const sink: Sink = {
-    logs: [], events: [], audits: [], errors: [], costs: [], indexed: [], spans: [],
-    outbox: [], gateOrder: [], quota: { reserved: [], committed: [], released: 0 },
-    files: [], queries: [],
-  }
-  const store = new MemoryStore(opts?.entities, opts?.keys)
-  const queue = new MemoryQueue()
-  const searchIdx = new Map<string, Row[]>()
-
-  const telemetry: Telemetry = {
-    start(action) {
-      let status: 'ok' | 'error' = 'ok'
-      return {
-        ok() { status = 'ok' },
-        error() { status = 'error' },
-        end() { sink.spans.push({ action, status }) },
-      }
-    },
-  }
-  const log: Log = { write(level, action, _actor, data) { sink.logs.push({ level, action, data }) } }
-
-  const audit: Audit = { async append(_actor, record) { sink.audits.push(record) } }
-  const errors: Errors = { async record(_actor, record) { sink.errors.push(record) } }
-  const cost: Cost = { meter(action) { sink.costs.push(action) } }
-  const events: EventBus = { async publish(e) { sink.events.push(e) } }
-  const rateLimiter: RateLimiter = {
-    async check() {
-      sink.gateOrder.push('rate')
-      return opts?.allowRate ?? true
-    },
-    async checkPolicy() {
-      sink.gateOrder.push('rate')
-      return opts?.allowRate ?? true
-    },
-  }
-
-  const featureGate: FeatureGate | undefined =
-    opts?.features === undefined
-      ? undefined
-      : {
-          async check(_actor, feature) {
-            sink.gateOrder.push('feature')
-            return (opts.features ?? []).includes(feature)
-          },
-        }
-
-  const used = new Map<string, number>()
-  const quotas: Quotas | undefined =
-    opts?.quota === undefined
-      ? undefined
-      : {
-          async reserve(_actor, meter, estimate) {
-            sink.gateOrder.push('quota')
-            sink.quota.reserved.push(estimate)
-
-            const allowance = opts.quota?.[meter] ?? Number.POSITIVE_INFINITY
-            const before = used.get(meter) ?? 0
-
-            if (before + estimate > allowance) {
-
-              return {
-                ok: false,
-                behavior: opts.onExceed ?? 'block',
-                retryAfterSeconds: 60,
-                async commit() {},
-                async release() {},
-              }
-            }
-
-            used.set(meter, before + estimate)
-            let settled = false
-            return {
-              ok: true,
-              behavior: null,
-              retryAfterSeconds: 0,
-              async commit(actual) {
-                if (settled) return
-                settled = true
-                sink.quota.committed.push(actual)
-                used.set(meter, (used.get(meter) ?? 0) - estimate + actual)
-              },
-              async release() {
-                if (settled) return
-                settled = true
-                sink.quota.released += 1
-                used.set(meter, (used.get(meter) ?? 0) - estimate)
-              },
-            }
-          },
-        }
-
-  const outbox: Outbox = {
-    async emit(_actor, event) {
-      sink.outbox.push(event)
-    },
-  }
-
-  const idempotency: Idempotency = new MemoryIdempotency({
-    onCheck: () => sink.gateOrder.push('idempotency'),
-  })
-  const search: Search = {
-    async index(_actor, entity, row) {
-      sink.indexed.push({ entity, row })
-      searchIdx.set(entity, [...(searchIdx.get(entity) ?? []), row])
-    },
-    async query(_actor, entity, q) {
-
-      const needle = q.toLowerCase()
-      return (searchIdx.get(entity) ?? []).filter((r) => JSON.stringify(r).toLowerCase().includes(needle))
-    },
-  }
-
-  const vault: Vault | undefined = opts?.secrets === undefined ? undefined : memoryVault(opts.secrets)
-
-  const stored = new Map<string, { body: Uint8Array; contentType: string }>()
-  const files: Files = {
-    async put(_actor, key, body, contentType) {
-      stored.set(key, { body, contentType })
-      sink.files.push({ action: 'put', key, bytes: body.byteLength })
-      return { size: body.byteLength }
-    },
-    async get(_actor, key) {
-      const found = stored.get(key)
-      sink.files.push({ action: 'get', key, bytes: found === undefined ? null : found.body.byteLength })
-      return found === undefined ? null : { body: found.body, contentType: found.contentType }
-    },
-    async signedUrl(_actor, key, expiresInSeconds) {
-      sink.files.push({ action: 'signed', key, bytes: null })
-      return `https://files.invalid/unsigned-in-memory/${encodeURIComponent(key)}?expires_in=${String(expiresInSeconds)}`
-    },
-    async remove(_actor, key) {
-      stored.delete(key)
-      sink.files.push({ action: 'remove', key, bytes: null })
-    },
-  }
-
-  const answers = opts?.views
-  const views: Views | undefined =
-    answers === undefined
-      ? undefined
-      : {
-          async query<T>(_actor: Actor, sql: string, params: readonly unknown[]) {
-            const found = (answers[sql] ?? []) as readonly T[]
-            sink.queries.push({ sql, params, rows: found.length })
-            return found
-          },
-        }
-
-  return {
-    seams: {
-      store, telemetry, log, audit, errors, search, cost, idempotency, events, rateLimiter, queue,
-      outbox, files, clock: { now: arrived }, random: { next: Math.random, uuid: fresh },
-      ...(featureGate ? { featureGate } : {}),
-      ...(quotas ? { quotas } : {}),
-      ...(vault ? { vault } : {}),
-      ...(views ? { views } : {}),
-    },
-    sink, store, queue,
-  }
-}

package/dist/operations/metering.d.ts

@@ -1,55 +0,0 @@
-import { PlatformError } from './errors/catalog.ts';
-import type { PropertyValue, Search, Seams, Store, Views } from './seams.ts';
-export interface ActionBudget {
-    readonly roundTrips: number;
-}
-export interface WriteAmplification {
-    readonly entity: string;
-    readonly id: string;
-    readonly columns: readonly string[];
-    readonly bytes: number;
-}
-export interface DatabaseUsage {
-    readonly roundTrips: number;
-    readonly rowsRead: number;
-    readonly rowsWritten: number;
-    readonly bytesRead: number;
-    readonly bytesWritten: number;
-    readonly amplified: readonly WriteAmplification[];
-}
-export declare class RoundTripBudgetExceededError extends PlatformError {
-    readonly budget: number;
-    readonly refusedStatement: string;
-    constructor(budget: number, statement: string);
-}
-export declare const BUDGET_EXCEEDED_BECAUSE = "round_trip_budget_exceeded";
-export declare const DB_USAGE_PROPERTY = "db";
-export declare const DB_USAGE_ATTRIBUTES: {
-    readonly roundTrips: "thread.db.round_trips";
-    readonly rowsRead: "thread.db.rows_read";
-    readonly rowsWritten: "thread.db.rows_written";
-    readonly bytesRead: "thread.db.bytes_read";
-    readonly bytesWritten: "thread.db.bytes_written";
-    readonly budgetRoundTrips: "thread.db.budget_round_trips";
-};
-export declare const DB_AMPLIFICATION_PROPERTY = "db_amplification";
-export declare const DB_AMPLIFICATION_ATTRIBUTES: {
-    readonly entities: "thread.db.amplified_entities";
-    readonly columns: "thread.db.amplified_columns";
-    readonly bytes: "thread.db.amplified_bytes";
-    readonly writes: "thread.db.amplified_writes";
-};
-export declare function databaseUsageValues(usage: DatabaseUsage, budget?: ActionBudget): Readonly<Record<string, PropertyValue>>;
-export declare function writeAmplificationValues(usage: DatabaseUsage): Readonly<Record<string, PropertyValue>> | undefined;
-export declare function payloadBytes(value: unknown, depth?: number): number;
-export interface MeterableSeams {
-    readonly store?: Store;
-    readonly search?: Search;
-    readonly views?: Views;
-}
-export interface Metered<S> {
-    readonly seams: S;
-    usage(): DatabaseUsage;
-}
-export type MeteredSeams = Metered<Seams>;
-export declare function meterDatabase<S extends MeterableSeams>(seams: S, budget?: ActionBudget): Metered<S>;