@nifrajs/core 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Bun-native, contract-first HTTP framework - the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -167,6 +167,21 @@
       "types": "./dist/classification.d.ts",
       "default": "./dist/classification.js"
     },
+    "./channel": {
+      "bun": "./src/channel.ts",
+      "types": "./dist/channel.d.ts",
+      "default": "./dist/channel.js"
+    },
+    "./data": {
+      "bun": "./src/data.ts",
+      "types": "./dist/data.d.ts",
+      "default": "./dist/data.js"
+    },
+    "./range": {
+      "bun": "./src/range.ts",
+      "types": "./dist/range.d.ts",
+      "default": "./dist/range.js"
+    },
     "./contract": {
       "bun": "./src/server/contract.ts",
       "types": "./dist/server/contract.d.ts",

package/src/channel.ts

@@ -0,0 +1,299 @@
+/** Typed, runtime-neutral channel contracts. Durable replay, presence, fan-out, and tenant-aware
+ * routing belong in an adapter; the bundled hub provides only bounded process-local replay for tests
+ * and local development. */
+
+export interface ChannelContract<Name extends string, Message> {
+  readonly name: Name
+  /** Type-only message witness; adapters never materialize it. */
+  readonly __message?: (value: Message) => Message
+}
+
+export interface ChannelEvent<Message> {
+  /** Monotonic within one channel; adapters may use a different opaque cursor representation. */
+  readonly sequence: number
+  readonly resumeToken: string
+  readonly data: Message
+}
+
+export type ChannelCloseReason = "closed" | "backpressure" | "aborted"
+
+export interface ChannelSubscription<Message> extends AsyncIterableIterator<ChannelEvent<Message>> {
+  readonly channel: string
+  readonly closed: boolean
+  readonly closeReason: ChannelCloseReason | undefined
+  readonly resumeToken: string | undefined
+  close(): void
+}
+
+export interface ChannelSubscribeOptions {
+  /** Maximum undelivered events retained for this subscriber. Default 64. */
+  readonly maxQueue?: number
+  /** Resume after this opaque cursor. The adapter must fail closed when the cursor is unavailable. */
+  readonly resumeFrom?: string
+  readonly signal?: AbortSignal
+}
+
+export interface ChannelHub {
+  subscribe<Name extends string, Message>(
+    channel: ChannelContract<Name, Message>,
+    options?: ChannelSubscribeOptions,
+  ): ChannelSubscription<Message>
+  publish<Name extends string, Message>(
+    channel: ChannelContract<Name, Message>,
+    data: Message,
+  ): ChannelEvent<Message>
+}
+
+export interface MemoryChannelHubOptions {
+  /** Default queue bound per subscriber. Default 64. */
+  readonly maxQueue?: number
+  /** Maximum events retained per channel for local cursor replay. Default: the queue bound. */
+  readonly historySize?: number
+}
+
+/** A requested cursor is malformed, belongs to another channel, or fell outside retained history. */
+export class ChannelResumeUnavailableError extends Error {
+  readonly channel: string
+  readonly resumeToken: string
+
+  constructor(channel: string, resumeToken: string) {
+    super("channel: resume cursor is unavailable")
+    this.name = "ChannelResumeUnavailableError"
+    this.channel = channel
+    this.resumeToken = resumeToken
+  }
+}
+
+function validName(name: string): boolean {
+  return /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/.test(name)
+}
+
+/** Define a typed channel name. Message types are erased; adapters own validation at their boundary. */
+export function defineChannel<Name extends string, Message>(
+  name: Name,
+): ChannelContract<Name, Message> {
+  if (!validName(name)) throw new TypeError("channel: name must be a bounded token")
+  return Object.freeze({ name })
+}
+
+type Waiter<Message> = (result: IteratorResult<ChannelEvent<Message>>) => void
+
+class MemorySubscription<Message> implements ChannelSubscription<Message> {
+  readonly channel: string
+  private readonly maxQueue: number
+  private readonly remove: () => void
+  private readonly queue: ChannelEvent<Message>[] = []
+  private readonly waiters: Waiter<Message>[] = []
+  private isClosed = false
+  private reason: ChannelCloseReason | undefined
+  private lastToken: string | undefined
+  private abortSignal: AbortSignal | undefined
+  private abortHandler: (() => void) | undefined
+
+  constructor(channel: string, maxQueue: number, remove: () => void) {
+    this.channel = channel
+    this.maxQueue = maxQueue
+    this.remove = remove
+  }
+
+  seed(events: readonly ChannelEvent<Message>[]): void {
+    if (events.length > this.maxQueue) {
+      throw new RangeError("channel: resume history exceeds subscriber queue bound")
+    }
+    this.queue.push(...events)
+  }
+
+  attachSignal(signal: AbortSignal | undefined): void {
+    if (signal === undefined || this.isClosed) return
+    const handler = (): void => this.close("aborted")
+    this.abortSignal = signal
+    this.abortHandler = handler
+    signal.addEventListener("abort", handler, { once: true })
+    // Check after registration as well: an abort can happen between the initial caller check and
+    // listener registration in host implementations. `close()` removes the listener again.
+    if (signal.aborted) this.close("aborted")
+  }
+
+  get closed(): boolean {
+    return this.isClosed
+  }
+
+  get closeReason(): ChannelCloseReason | undefined {
+    return this.reason
+  }
+
+  get resumeToken(): string | undefined {
+    return this.lastToken
+  }
+
+  push(event: ChannelEvent<Message>): void {
+    if (this.isClosed) return
+    const waiter = this.waiters.shift()
+    if (waiter !== undefined) {
+      this.lastToken = event.resumeToken
+      waiter({ done: false, value: event })
+      return
+    }
+    if (this.queue.length >= this.maxQueue) {
+      this.close("backpressure")
+      return
+    }
+    this.queue.push(event)
+  }
+
+  next(): Promise<IteratorResult<ChannelEvent<Message>>> {
+    const event = this.queue.shift()
+    if (event !== undefined) {
+      this.lastToken = event.resumeToken
+      return Promise.resolve({ done: false, value: event })
+    }
+    if (this.isClosed) return Promise.resolve({ done: true, value: undefined })
+    return new Promise((resolve) => this.waiters.push(resolve))
+  }
+
+  return(): Promise<IteratorResult<ChannelEvent<Message>>> {
+    this.close("closed")
+    return Promise.resolve({ done: true, value: undefined })
+  }
+
+  close(reason: ChannelCloseReason = "closed"): void {
+    if (this.isClosed) return
+    this.isClosed = true
+    this.reason = reason
+    this.queue.length = 0
+    if (this.abortSignal !== undefined && this.abortHandler !== undefined) {
+      this.abortSignal.removeEventListener("abort", this.abortHandler)
+      this.abortSignal = undefined
+      this.abortHandler = undefined
+    }
+    this.remove()
+    for (const waiter of this.waiters.splice(0)) waiter({ done: true, value: undefined })
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<ChannelEvent<Message>> {
+    return this
+  }
+}
+
+/** A bounded in-memory hub suitable for tests and local development, never for durable fan-out. */
+export function memoryChannelHub(options: MemoryChannelHubOptions = {}): ChannelHub {
+  const maxQueue = options.maxQueue ?? 64
+  if (!Number.isSafeInteger(maxQueue) || maxQueue < 1) {
+    throw new RangeError("channel: maxQueue must be a positive safe integer")
+  }
+  const historySize = options.historySize ?? maxQueue
+  if (!Number.isSafeInteger(historySize) || historySize < 0) {
+    throw new RangeError("channel: historySize must be a non-negative safe integer")
+  }
+  const subscribers = new Map<string, Set<MemorySubscription<unknown>>>()
+  const sequences = new Map<string, number>()
+  const history = new Map<string, ChannelEvent<unknown>[]>()
+
+  const tokenFor = (channel: string, sequence: number): string =>
+    `${channel}:${sequence.toString(36)}`
+
+  const sequenceOf = (channel: string, token: string): number | undefined => {
+    const prefix = `${channel}:`
+    if (!token.startsWith(prefix)) return undefined
+    const digits = token.slice(prefix.length)
+    if (!/^[0-9a-z]+$/.test(digits)) return undefined
+    const sequence = Number.parseInt(digits, 36)
+    return Number.isSafeInteger(sequence) && sequence > 0 ? sequence : undefined
+  }
+
+  return {
+    subscribe<Name extends string, Message>(
+      channel: ChannelContract<Name, Message>,
+      subscriptionOptions: ChannelSubscribeOptions = {},
+    ): ChannelSubscription<Message> {
+      const queue = subscriptionOptions.maxQueue ?? maxQueue
+      if (!Number.isSafeInteger(queue) || queue < 1) {
+        throw new RangeError("channel: maxQueue must be a positive safe integer")
+      }
+      const currentSequence = sequences.get(channel.name) ?? 0
+      const resumeFrom = subscriptionOptions.resumeFrom
+      let replay: readonly ChannelEvent<unknown>[] = []
+      if (resumeFrom !== undefined) {
+        const requestedSequence = sequenceOf(channel.name, resumeFrom)
+        const channelHistory = history.get(channel.name) ?? []
+        const oldest = channelHistory[0]?.sequence
+        const known =
+          requestedSequence !== undefined &&
+          requestedSequence <= currentSequence &&
+          (requestedSequence === currentSequence ||
+            channelHistory.some((event) => event.sequence === requestedSequence))
+        if (!known) throw new ChannelResumeUnavailableError(channel.name, resumeFrom)
+        replay = channelHistory.filter((event) => event.sequence > requestedSequence)
+        // Keep this explicit so a future history representation cannot silently truncate a resume.
+        if (oldest !== undefined && requestedSequence < oldest && replay.length === 0) {
+          throw new ChannelResumeUnavailableError(channel.name, resumeFrom)
+        }
+        if (replay.length > queue) {
+          throw new ChannelResumeUnavailableError(channel.name, resumeFrom)
+        }
+      }
+      let members = subscribers.get(channel.name)
+      if (members === undefined) {
+        members = new Set()
+        subscribers.set(channel.name, members)
+      }
+      let subscription: MemorySubscription<unknown>
+      const remove = (): void => {
+        members?.delete(subscription)
+        if (members?.size === 0) subscribers.delete(channel.name)
+      }
+      subscription = new MemorySubscription(channel.name, queue, remove)
+      subscription.seed(replay)
+      members.add(subscription)
+      subscription.attachSignal(subscriptionOptions.signal)
+      return subscription as unknown as ChannelSubscription<Message>
+    },
+    publish<Name extends string, Message>(
+      channel: ChannelContract<Name, Message>,
+      data: Message,
+    ): ChannelEvent<Message> {
+      const previous = sequences.get(channel.name) ?? 0
+      if (previous === Number.MAX_SAFE_INTEGER) {
+        throw new RangeError("channel: sequence space exhausted")
+      }
+      const sequence = previous + 1
+      sequences.set(channel.name, sequence)
+      const event: ChannelEvent<Message> = {
+        sequence,
+        resumeToken: tokenFor(channel.name, sequence),
+        data,
+      }
+      if (historySize > 0) {
+        const channelHistory = history.get(channel.name) ?? []
+        channelHistory.push(event as unknown as ChannelEvent<unknown>)
+        if (channelHistory.length > historySize) channelHistory.shift()
+        history.set(channel.name, channelHistory)
+      }
+      for (const subscriber of subscribers.get(channel.name) ?? []) {
+        subscriber.push(event as unknown as ChannelEvent<unknown>)
+      }
+      return event
+    },
+  }
+}
+
+/** Adapt a channel subscription to a cancellable Web stream for SSE/HTTP adapters. */
+export function channelReadableStream<Message>(
+  subscription: ChannelSubscription<Message>,
+): ReadableStream<ChannelEvent<Message>> {
+  const iterator = subscription[Symbol.asyncIterator]()
+  return new ReadableStream<ChannelEvent<Message>>({
+    async pull(controller) {
+      try {
+        const result = await iterator.next()
+        if (result.done) controller.close()
+        else controller.enqueue(result.value)
+      } catch (error) {
+        controller.error(error)
+      }
+    },
+    cancel() {
+      subscription.close()
+    },
+  })
+}

package/src/data.ts

@@ -0,0 +1,292 @@
+/** Public, token-only data access contracts. Durable adapters and RLS policy enforcement stay outside
+ * this package; this subpath defines the typed seam they implement. */
+
+export const DATA_CAPABILITIES = Object.freeze({
+  read: "db.read",
+  write: "db.write",
+} as const)
+
+export type DataAccess = keyof typeof DATA_CAPABILITIES
+export type DataCapability = (typeof DATA_CAPABILITIES)[DataAccess]
+
+export interface DataOperationSpec {
+  readonly access: DataAccess
+  readonly input?: unknown
+  readonly output?: unknown
+}
+
+export type DataOperationMap = Readonly<Record<string, DataOperationSpec>>
+
+export interface DataContract<Operations extends DataOperationMap = DataOperationMap> {
+  readonly version: string
+  readonly operations: Operations
+}
+
+/** Opaque request-local RLS (or equivalent data-policy) scope passed to an adapter. */
+export interface RlsScope {
+  /** Caller-owned scope token. The public seam never interprets, logs, or derives identity from it. */
+  readonly token: string
+  /** Optional opaque digest for correlating a scope without exposing tenant or subject data. */
+  readonly digest?: string
+}
+
+/** Backward-compatible name for the request scope carried by every data operation. */
+export type DataScope = RlsScope
+
+export interface DataRequest<Operation extends string = string, Input = unknown> {
+  readonly operation: Operation
+  readonly scope: DataScope
+  readonly capability: DataCapability
+  readonly input: Input
+}
+
+export interface DataDrift {
+  readonly kind: "version" | "added" | "removed" | "access-changed"
+  readonly operation?: string
+  readonly declaredAccess?: DataAccess
+  readonly observedAccess?: DataAccess
+  readonly declaredVersion?: string
+  readonly observedVersion?: string
+}
+
+type InputOf<Operation> = Operation extends { readonly input: infer Input } ? Input : never
+type OutputOf<Operation> = Operation extends { readonly output: infer Output } ? Output : unknown
+type CapabilityOf<Operation> = Operation extends { readonly access: "read" }
+  ? typeof DATA_CAPABILITIES.read
+  : Operation extends { readonly access: "write" }
+    ? typeof DATA_CAPABILITIES.write
+    : DataCapability
+type InputField<Input> = [Input] extends [never]
+  ? { readonly input?: never }
+  : { readonly input: Input }
+
+export type DataInput<
+  Contract extends DataContract,
+  Operation extends keyof Contract["operations"] & string,
+> = Contract["operations"][Operation] extends infer Definition ? InputOf<Definition> : never
+
+export type DataOutput<
+  Contract extends DataContract,
+  Operation extends keyof Contract["operations"] & string,
+> = Contract["operations"][Operation] extends infer Definition ? OutputOf<Definition> : unknown
+
+export type DataRequestFor<
+  Contract extends DataContract,
+  Operation extends keyof Contract["operations"] & string,
+> = {
+  readonly operation: Operation
+  readonly scope: DataScope
+  readonly capability: CapabilityOf<Contract["operations"][Operation]>
+} & InputField<DataInput<Contract, Operation>>
+
+export interface TypedDataPort<Contract extends DataContract> {
+  execute<Operation extends keyof Contract["operations"] & string>(
+    request: DataRequestFor<Contract, Operation>,
+  ): Promise<DataOutput<Contract, Operation>>
+}
+
+/** Runtime capability beacon used by a request-bound data port. */
+export type DataCapabilityBeacon = (context: object, capability: DataCapability) => void
+
+/** Options for the public request-bound data port wrapper. */
+export interface DataPortOptions {
+  /** Usually `useCapability` from `@nifrajs/core/capabilities`. */
+  readonly beacon?: DataCapabilityBeacon
+}
+
+/** A data port bound to one request context; every operation emits capability evidence first. */
+export interface BoundDataPort<Contract extends DataContract> extends TypedDataPort<Contract> {}
+
+/** Public factory for wiring a private data adapter into Nifra's capability evidence chain. */
+export interface DataPort<Contract extends DataContract> {
+  for(context: object): BoundDataPort<Contract>
+}
+
+/**
+ * Bind a private data adapter to request-local capability evidence.
+ *
+ * The adapter remains responsible for RLS enforcement and durable storage. This wrapper owns the
+ * framework-side proof boundary: it emits exactly the operation's typed `db.read`/`db.write` token
+ * before invoking the adapter, and refuses to run when no beacon is configured or the beacon denies
+ * the operation. The context is never copied into the request or retained by the port.
+ *
+ * The emitted token is derived from the **contract**, never from `request.capability`. The typed
+ * request narrows that field, but types are erased before this line runs, and a request assembled
+ * from decoded input would otherwise let a write operation announce itself as `db.read` - evidence
+ * that names the wrong capability is worse than no evidence, because the ledger looks satisfied. An
+ * unknown operation, or a declared capability that disagrees with the contract, fails closed.
+ */
+export function createDataPort<Contract extends DataContract>(
+  contract: Contract,
+  adapter: TypedDataPort<Contract>,
+  options: DataPortOptions = {},
+): DataPort<Contract> {
+  if (contract === null || typeof contract !== "object" || contract.operations === undefined) {
+    throw new TypeError("data: contract must be a defineDataContract result")
+  }
+  if (adapter === null || typeof adapter !== "object" || typeof adapter.execute !== "function") {
+    throw new TypeError("data: adapter must implement execute(request)")
+  }
+
+  function bind(context: object): BoundDataPort<Contract> {
+    if (context === null || typeof context !== "object") {
+      throw new TypeError("data: context must be an object")
+    }
+    const beacon = options.beacon
+    if (beacon === undefined) {
+      throw new Error(
+        "@nifrajs/core/data: for(context) needs a beacon - pass `beacon: useCapability` to createDataPort",
+      )
+    }
+    return Object.freeze({
+      execute<Operation extends keyof Contract["operations"] & string>(
+        request: DataRequestFor<Contract, Operation>,
+      ): Promise<DataOutput<Contract, Operation>> {
+        const declared = contract.operations[request.operation]
+        if (declared === undefined || !isDataAccess(declared.access)) {
+          return Promise.reject(
+            new TypeError(`data: ${String(request.operation)} is not declared by this contract`),
+          )
+        }
+        const capability = DATA_CAPABILITIES[declared.access]
+        if (request.capability !== capability) {
+          return Promise.reject(
+            new TypeError(`data: ${String(request.operation)} requires ${capability}`),
+          )
+        }
+        try {
+          beacon(context, capability)
+        } catch (error) {
+          return Promise.reject(error)
+        }
+        return adapter.execute(request)
+      },
+    })
+  }
+
+  return Object.freeze({ for: bind })
+}
+
+function assertToken(value: string, label: string): string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 256 ||
+    hasControlCharacter(value)
+  ) {
+    throw new TypeError(`data: ${label} must be a bounded opaque token`)
+  }
+  return value
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if (code <= 31 || code === 127) return true
+  }
+  return false
+}
+
+/** Create a bounded, opaque RLS/equivalent policy scope for a data adapter. */
+export function rlsScope(token: string, digest?: string): RlsScope {
+  const scope = {
+    token: assertToken(token, "scope token"),
+    ...(digest === undefined ? {} : { digest: assertToken(digest, "scope digest") }),
+  }
+  return Object.freeze(scope)
+}
+
+/** Backward-compatible constructor for {@link RlsScope}. */
+export function dataScope(token: string, digest?: string): DataScope {
+  return rlsScope(token, digest)
+}
+
+function isDataAccess(value: unknown): value is DataAccess {
+  return value === "read" || value === "write"
+}
+
+function validVersion(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= 128 &&
+    !hasControlCharacter(value)
+  )
+}
+
+function validOperationName(value: string): boolean {
+  return /^[A-Za-z][A-Za-z0-9._-]{0,127}$/.test(value)
+}
+
+/** Define and freeze a token-only data contract. Input/output types are erased at runtime. */
+export function defineDataContract<const Operations extends DataOperationMap>(input: {
+  readonly version: string
+  readonly operations: Operations
+}): DataContract<Operations> {
+  if (!validVersion(input.version)) throw new TypeError("data: version must be a bounded token")
+  if (input.operations === null || typeof input.operations !== "object") {
+    throw new TypeError("data: operations must be an object")
+  }
+  const operations: Record<string, DataOperationSpec> = {}
+  for (const [name, operation] of Object.entries(input.operations)) {
+    if (!validOperationName(name)) throw new TypeError(`data: invalid operation name ${name}`)
+    if (operation === null || typeof operation !== "object" || !isDataAccess(operation.access)) {
+      throw new TypeError(`data: ${name} must declare read or write access`)
+    }
+    // `input` and `output` are type witnesses only. Never retain runtime schemas, defaults, or
+    // caller-owned values in the public contract object; adapters receive only token metadata.
+    operations[name] = Object.freeze({ access: operation.access })
+  }
+  return Object.freeze({
+    version: input.version,
+    operations: Object.freeze(operations) as Operations,
+  })
+}
+
+export interface DataContractSnapshot {
+  readonly version: string
+  readonly operations: Readonly<Record<string, { readonly access: DataAccess }>>
+}
+
+/** Strip a contract to its token-only version/access snapshot for CI or adapter drift checks. */
+export function snapshotDataContract(contract: DataContract): DataContractSnapshot {
+  const operations: Record<string, { readonly access: DataAccess }> = {}
+  for (const [name, operation] of Object.entries(contract.operations)) {
+    if (isDataAccess(operation.access)) operations[name] = { access: operation.access }
+  }
+  return Object.freeze({ version: contract.version, operations: Object.freeze(operations) })
+}
+
+/** Compare a declared contract with an adapter-observed token-only snapshot. */
+export function diffDataContract(
+  declared: DataContract,
+  observed: DataContractSnapshot | DataContract,
+): readonly DataDrift[] {
+  const left = snapshotDataContract(declared)
+  const right = "operations" in observed ? snapshotDataContract(observed) : observed
+  const drift: DataDrift[] = []
+  if (left.version !== right.version) {
+    drift.push({
+      kind: "version",
+      declaredVersion: left.version,
+      observedVersion: right.version,
+    })
+  }
+  for (const [name, operation] of Object.entries(left.operations)) {
+    const candidate = right.operations[name]
+    if (candidate === undefined) {
+      drift.push({ kind: "removed", operation: name })
+    } else if (candidate.access !== operation.access) {
+      drift.push({
+        kind: "access-changed",
+        operation: name,
+        declaredAccess: operation.access,
+        observedAccess: candidate.access,
+      })
+    }
+  }
+  for (const [name] of Object.entries(right.operations)) {
+    if (left.operations[name] === undefined) drift.push({ kind: "added", operation: name })
+  }
+  return Object.freeze(drift)
+}

package/src/index.ts

@@ -10,7 +10,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.9.0" as const
+export const VERSION = "2.10.0" as const
 
 export type Version = typeof VERSION