@prestack/thread 0.0.1 → 0.0.2

package/dist/operations/metering.ts

@@ -0,0 +1,328 @@
+import { PlatformError } from './errors/catalog.ts'
+import { DbRoundTripBudgetExceeded } from './errors/errors.ts'
+
+import type { Actor } from '../core/actor.ts'
+import type { PropertyValue, Row, Search, Seams, Store, Transactional, Views } from './seams.ts'
+import { isTransactional } 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 class RoundTripBudgetExceededError extends PlatformError {
+  readonly budget: number
+
+  readonly refusedStatement: string
+
+  constructor(budget: number, statement: string) {
+    const detail =
+      `this operation declared a budget of ${budget} database round trip(s) and asked for ` +
+      `"${statement}" as number ${budget + 1}`
+
+    super(DbRoundTripBudgetExceeded.def, { detail, because: BUDGET_EXCEEDED_BECAUSE })
+    this.name = 'RoundTripBudgetExceededError'
+
+    this.message = detail
+    this.budget = budget
+    this.refusedStatement = statement
+  }
+}
+
+export const BUDGET_EXCEEDED_BECAUSE = 'round_trip_budget_exceeded'
+
+export const DB_USAGE_PROPERTY = 'db'
+
+export const DB_USAGE_ATTRIBUTES = {
+  roundTrips: 'thread.db.round_trips',
+  rowsRead: 'thread.db.rows_read',
+  rowsWritten: 'thread.db.rows_written',
+  bytesRead: 'thread.db.bytes_read',
+  bytesWritten: 'thread.db.bytes_written',
+  budgetRoundTrips: 'thread.db.budget_round_trips',
+} as const
+
+export const DB_AMPLIFICATION_PROPERTY = 'db_amplification'
+
+export const DB_AMPLIFICATION_ATTRIBUTES = {
+  entities: 'thread.db.amplified_entities',
+  columns: 'thread.db.amplified_columns',
+  bytes: 'thread.db.amplified_bytes',
+  writes: 'thread.db.amplified_writes',
+} as const
+
+export function databaseUsageValues(
+  usage: DatabaseUsage,
+  budget?: ActionBudget,
+): Readonly<Record<string, PropertyValue>> {
+  return {
+    [DB_USAGE_ATTRIBUTES.roundTrips]: usage.roundTrips,
+    [DB_USAGE_ATTRIBUTES.rowsRead]: usage.rowsRead,
+    [DB_USAGE_ATTRIBUTES.rowsWritten]: usage.rowsWritten,
+    [DB_USAGE_ATTRIBUTES.bytesRead]: usage.bytesRead,
+    [DB_USAGE_ATTRIBUTES.bytesWritten]: usage.bytesWritten,
+    ...(budget === undefined ? {} : { [DB_USAGE_ATTRIBUTES.budgetRoundTrips]: budget.roundTrips }),
+  }
+}
+
+export function writeAmplificationValues(
+  usage: DatabaseUsage,
+): Readonly<Record<string, PropertyValue>> | undefined {
+  if (usage.amplified.length === 0) return undefined
+
+  const entities = [...new Set(usage.amplified.map((write) => write.entity))]
+  const columns = [...new Set(usage.amplified.flatMap((write) => write.columns))]
+
+  return {
+    [DB_AMPLIFICATION_ATTRIBUTES.entities]: entities.join(','),
+    [DB_AMPLIFICATION_ATTRIBUTES.columns]: columns.join(','),
+    [DB_AMPLIFICATION_ATTRIBUTES.bytes]: usage.amplified.reduce((total, write) => total + write.bytes, 0),
+    [DB_AMPLIFICATION_ATTRIBUTES.writes]: usage.amplified.length,
+  }
+}
+
+const MAX_WALK_DEPTH = 24
+
+function utf8Length(text: string): number {
+  let bytes = 0
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index)
+    if (code < 0x80) bytes += 1
+    else if (code < 0x800) bytes += 2
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length) {
+
+      bytes += 4
+      index += 1
+    } else bytes += 3
+  }
+  return bytes
+}
+
+export function payloadBytes(value: unknown, depth = 0): number {
+  if (value === null || value === undefined) return 0
+  if (depth > MAX_WALK_DEPTH) return 0
+
+  switch (typeof value) {
+    case 'string':
+      return utf8Length(value)
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+
+      return 8
+    case 'object':
+      break
+    default:
+
+      return 0
+  }
+
+  if (value instanceof Date) return 8
+  if (value instanceof Uint8Array) return value.byteLength
+  if (Array.isArray(value)) {
+    let total = 0
+    for (const item of value) total += payloadBytes(item, depth + 1)
+    return total
+  }
+
+  let total = 0
+  for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+
+    total += utf8Length(key) + payloadBytes(nested, depth + 1)
+  }
+  return total
+}
+
+function sameStoredValue(left: unknown, right: unknown, depth = 0): boolean {
+  if (left === right) return true
+  if (depth > MAX_WALK_DEPTH) return false
+
+  if (left instanceof Date || right instanceof Date) {
+    return left instanceof Date && right instanceof Date && left.getTime() === right.getTime()
+  }
+  if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) return false
+  if (Array.isArray(left) !== Array.isArray(right)) return false
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((item, index) => sameStoredValue(item, right[index], depth + 1))
+  }
+
+  const a = left as Record<string, unknown>
+  const b = right as Record<string, unknown>
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  return keys.every((key) => key in b && sameStoredValue(a[key], b[key], depth + 1))
+}
+
+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 function meterDatabase<S extends MeterableSeams>(seams: S, budget?: ActionBudget): Metered<S> {
+  let roundTrips = 0
+  let rowsRead = 0
+  let rowsWritten = 0
+  let bytesRead = 0
+  let bytesWritten = 0
+  const amplified: WriteAmplification[] = []
+
+  const seen = new Map<string, Row>()
+  const remember = (entity: string, row: Row): void => {
+    seen.set(`${entity}:${row.id}`, row)
+  }
+
+  const spend = (statement: string): void => {
+    if (budget !== undefined && roundTrips >= budget.roundTrips) {
+
+      throw new RoundTripBudgetExceededError(budget.roundTrips, statement)
+    }
+    roundTrips += 1
+  }
+
+  const readRows = (rows: readonly unknown[]): void => {
+    rowsRead += rows.length
+    for (const row of rows) bytesRead += payloadBytes(row)
+  }
+
+  const base = seams.store
+
+  const store: (Store & Partial<Transactional>) | undefined = base === undefined ? undefined : {
+    async insert(actor, entity, row) {
+      spend(`insert ${entity}`)
+      bytesWritten += payloadBytes(row)
+      rowsWritten += 1
+      const written = await base.insert(actor, entity, row)
+      remember(entity, written)
+      return written
+    },
+
+    async get(actor, entity, id, fields) {
+      spend(`get ${entity}`)
+      const row = await base.get(actor, entity, id, fields)
+      if (row !== null) {
+        rowsRead += 1
+        bytesRead += payloadBytes(row)
+        remember(entity, row)
+      }
+      return row
+    },
+
+    async list(actor, entity, opts) {
+      spend(`list ${entity}`)
+      const rows = await base.list(actor, entity, opts)
+      readRows(rows)
+      for (const row of rows) remember(entity, row)
+      return rows
+    },
+
+    async update(actor, entity, id, patch, expectedVersion) {
+      spend(`update ${entity}`)
+      recordAmplification(entity, id, patch)
+      bytesWritten += payloadBytes(patch)
+      rowsWritten += 1
+      const row = await base.update(actor, entity, id, patch, expectedVersion)
+      remember(entity, row)
+      return row
+    },
+
+    async remove(actor, entity, id) {
+
+      spend(`remove ${entity}`)
+      rowsWritten += 1
+      await base.remove(actor, entity, id)
+      seen.delete(`${entity}:${id}`)
+    },
+  }
+
+  if (base !== undefined && store !== undefined && isTransactional(base)) {
+    store.transaction = (actor, fn) => base.transaction(actor, fn)
+  }
+
+  function recordAmplification(entity: string, id: string | number, patch: Record<string, unknown>): void {
+    const stored = seen.get(`${entity}:${id}`)
+    if (stored === undefined) return
+
+    const columns: string[] = []
+    let bytes = 0
+    for (const [column, value] of Object.entries(patch)) {
+      if (!(column in stored)) continue
+      if (!sameStoredValue(value, stored[column])) continue
+      columns.push(column)
+      bytes += payloadBytes(value)
+    }
+
+    if (columns.length === 0) return
+    amplified.push({ entity, id: String(id), columns, bytes })
+  }
+
+  const views: Views | undefined =
+    seams.views === undefined
+      ? undefined
+      : {
+          async query<T = Record<string, unknown>>(
+            actor: Actor,
+            sql: string,
+            params: readonly unknown[],
+          ): Promise<readonly T[]> {
+            spend('view')
+            const rows = await (seams.views as Views).query<T>(actor, sql, params)
+            readRows(rows)
+            return rows
+          },
+        }
+
+  const baseSearch = seams.search
+  const search: Search | undefined =
+    baseSearch === undefined
+      ? undefined
+      : {
+          index: (actor, entity, row) => baseSearch.index(actor, entity, row),
+          async query(actor, entity, q) {
+            spend(`search ${entity}`)
+            const rows = await baseSearch.query(actor, entity, q)
+            readRows(rows)
+            return rows
+          },
+        }
+
+  const metered: MeterableSeams = {
+    ...(store === undefined ? {} : { store }),
+    ...(search === undefined ? {} : { search }),
+    ...(views === undefined ? {} : { views }),
+  }
+
+  return {
+    seams: { ...seams, ...metered } as S,
+    usage: () => ({ roundTrips, rowsRead, rowsWritten, bytesRead, bytesWritten, amplified }),
+  }
+}

package/dist/operations/nodes.ts

@@ -0,0 +1,54 @@
+import type { Threaded } from '../core/thread.ts'
+
+import type { Operation } from './operations.ts'
+import type { Handed, Reads, Supplied } from './seams.ts'
+
+export interface Node extends Threaded {
+  readonly version: number
+}
+
+export type Held<I = unknown> = Parameters<Operation<I>['run']>[1]
+
+export const STOPPED = Symbol.for('thread.operation.stopped')
+
+export function stopped(thrown: unknown): { readonly value: unknown } | undefined {
+  if (typeof thrown !== 'object' || thrown === null) return undefined
+  if ((thrown as Record<symbol, unknown>)[STOPPED] !== true) return undefined
+  return { value: (thrown as { readonly value?: unknown }).value }
+}
+
+export const nd_read = <I, R extends string = Supplied>(
+  block: (hands: Reads<Handed<R>>, held: Held<I>) => Promise<unknown>,
+) => ({ type: 'nd_read' as const })
+
+export const nd_action = <I, R extends string = Supplied>(
+  block: (hands: Handed<R>, held: Held<I>) => Promise<unknown>,
+) => ({ type: 'nd_action' as const })
+
+export const nd_branch = <I, R extends string = Supplied>(
+  choose: (hands: Reads<Handed<R>>, held: Held<I>) => Promise<string>,
+  ways: Readonly<Record<string, (hands: Handed<R>, held: Held<I>) => Promise<unknown>>>,
+) => ({ type: 'nd_branch' as const })
+
+export const nd_each = <I, R extends string = Supplied>(
+  over: (held: Held<I>) => readonly unknown[],
+  block: (item: unknown, hands: Handed<R>, held: Held<I>) => Promise<unknown>,
+) => ({ type: 'nd_each' as const })
+
+export const nd_parallel = <I, R extends string = Supplied>(
+  blocks: readonly ((hands: Handed<R>, held: Held<I>) => Promise<unknown>)[],
+) => ({ type: 'nd_parallel' as const })
+
+export const nd_repeat = <I, R extends string = Supplied>(
+  ceiling: number,
+  block: (
+    pass: number,
+    carried: unknown,
+    hands: Handed<R>,
+    held: Held<I>,
+  ) => Promise<{ readonly done: boolean; readonly value: unknown }>,
+) => ({ type: 'nd_repeat' as const })
+
+export const nd_stop = <I, R extends string = Supplied>(
+  block: (hands: Reads<Handed<R>>, held: Held<I>) => Promise<unknown>,
+) => ({ type: 'nd_stop' as const })

package/dist/operations/operations.ts

@@ -0,0 +1,32 @@
+import type { z } from 'zod'
+
+import type { Member } from '../core/thread.ts'
+
+import type { Handed, Row, Supplied } from './seams.ts'
+
+export const OPERATIONS_FILE = 'operations.ts'
+
+export const TRIALS_AT = 'operations/_trials.json'
+
+export const NODES_FILE = 'nodes.ts'
+
+export const MEMBERS_LIST = 'MEMBERS'
+
+export interface Operation<I = unknown, R extends string = Supplied> {
+  readonly id: string
+
+  readonly input: z.ZodType<I>
+
+  readonly requires: readonly string[]
+
+  readonly run: (
+    hands: Handed<R>,
+    held: { readonly input: I } & Readonly<Record<string, unknown>>,
+  ) => Promise<unknown>
+
+  readonly estimate: number
+
+  readonly resource: (input: I) => Row | null
+}
+
+export const OPERATIONS: readonly Member[] = []

package/dist/operations/queue-policy.ts

@@ -0,0 +1,10 @@
+export const MAX_ATTEMPTS = 5
+
+export function backoffMs(attempts: number): number {
+  const base = 1_000 * 2 ** Math.max(0, attempts - 1)
+  return Math.min(base, 5 * 60_000)
+}
+
+export function isExhausted(attempts: number): boolean {
+  return attempts >= MAX_ATTEMPTS
+}

package/dist/operations/result.ts

@@ -0,0 +1,28 @@
+import type { ErrorCode, ErrorDef } from './errors/catalog.ts'
+import type { ErrorClass } from './errors/classes.ts'
+
+export type ResultCode = 'denied' | 'invalid' | 'rate_limited' | 'feature_denied' | 'quota_exceeded' | 'error'
+
+export type FailureIdentity = Pick<ErrorDef, 'code' | 'class'>
+
+export type Result<O> =
+  | { ok: true; value: O }
+  | {
+      ok: false
+      code: ResultCode
+      error: string
+      because?: string
+      errorCode?: ErrorCode
+      errorClass?: ErrorClass
+    }
+
+export const ok = <O>(value: O): Result<O> => ({ ok: true, value })
+export const fail = <O>(code: ResultCode, error: string, because?: string, identity?: FailureIdentity): Result<O> => ({
+  ok: false,
+  code,
+  error,
+  because,
+  ...(identity === undefined ? {} : { errorCode: identity.code, errorClass: identity.class }),
+})
+
+export class ValidationError extends Error {}

package/dist/operations/seams.d.ts

@@ -179,10 +179,10 @@ export interface Vault {
     resolve(refs: readonly string[]): Promise<Readonly<Record<string, string>>>;
 }
 export interface Seams {
-    store: Store;
-    search: Search;
-    events: EventBus;
-    queue: Queue;
+    store?: Store;
+    search?: Search;
+    events?: EventBus;
+    queue?: Queue;
     telemetry?: Telemetry;
     log: Log;
     audit: Audit;