@c9up/ream 0.1.32 → 0.1.34

package/src/bootstrap/hyper-server.ts

@@ -22,16 +22,9 @@ import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { arch, platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
+import { NAPI_PLATFORM_MAP } from '../helpers/napi-loader.js'
 import type { HyperServerLike } from '../Ignitor.js'
 
-const PLATFORM_SUFFIX: Record<string, string> = {
-  'linux-x64': 'linux-x64-gnu',
-  'linux-arm64': 'linux-arm64-gnu',
-  'darwin-x64': 'darwin-x64',
-  'darwin-arm64': 'darwin-arm64',
-  'win32-x64': 'win32-x64-msvc',
-}
-
 interface HyperServerCtor {
   new (port: number, host?: string): HyperServerLike
 }
@@ -57,7 +50,7 @@ function isHyperServerNapi(value: unknown): value is HyperServerNapiModule {
 export function createHyperServerFactory():
   | ((port: number, host?: string) => HyperServerLike)
   | undefined {
-  const suffix = PLATFORM_SUFFIX[`${platform}-${arch}`]
+  const suffix = NAPI_PLATFORM_MAP[`${platform}-${arch}`]
   if (!suffix) return undefined
 
   const require2 = createRequire(import.meta.url)

package/src/container/Container.ts

@@ -19,6 +19,8 @@ import {
 } from '../decorators/Service.js'
 import { didYouMean } from '../errors/FuzzyMatcher.js'
 import { ReamError } from '../errors/ReamError.js'
+import { ContainerResolver } from './ContainerResolver.js'
+import { ContextualBindingsBuilder } from './ContextualBindingsBuilder.js'
 import type { Binding, ServiceFactory, ServiceToken } from './types.js'
 
 /**
@@ -32,11 +34,52 @@ const RESERVED_TOKEN_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
 interface ResolutionChain {
   stack: string[]
   set: Set<string>
+  /**
+   * Values bound on the {@link ContainerResolver} that opened this chain.
+   *
+   * Carried on the chain, not passed down each private method, so a value
+   * bound for one request is visible to everything that resolution triggers —
+   * a controller's constructor dependency sees the same `HttpContext` the
+   * middleware bound — and to nothing outside it.
+   */
+  values?: ReadonlyMap<string, unknown>
+  /**
+   * How many scoped values this chain has handed out so far.
+   *
+   * A singleton built while a request's values are in scope may have captured
+   * one — cache it app-wide and every later request gets the first request's
+   * `HttpContext`. Comparing this counter before and after a build says whether
+   * it actually read one, so a singleton that touched no request state still
+   * caches exactly as before.
+   */
+  scopedReads?: number
+  /**
+   * The class whose dependencies are being resolved right now.
+   *
+   * A contextual binding answers "when THIS class asks for that, give it
+   * this", so the lookup needs the direct dependent. Carried on the chain for
+   * the same reason the scoped values are: `#autoConstruct` knows it, and
+   * every method between there and the lookup would otherwise have to pass it
+   * down. Saved and restored around each construction, so a dependency's own
+   * dependencies see IT as their parent, not its parent.
+   */
+  parent?: new (
+    ...args: never[]
+  ) => unknown
 }
 
 export class Container {
   #bindings: Map<string, Binding> = new Map()
   #singletons: Map<string, unknown> = new Map()
+  /**
+   * Singletons currently being built, by key.
+   *
+   * The factory is async, so two resolves at cold start both get past the
+   * cache check and both run it — producing two instances where the whole
+   * point is one, and silently discarding the first (a second connection
+   * pool, a second scheduler). Concurrent callers await the same promise.
+   */
+  #pendingSingletons: Map<string, Promise<unknown>> = new Map()
   #overrides: Map<string, ServiceFactory> = new Map()
   /**
    * Snapshot of singletons taken when `swap`/`override` shadows a previously
@@ -47,6 +90,9 @@ export class Container {
   #singletonBackup: Map<string, unknown> = new Map()
   /** Alias key → the token it forwards to (AdonisJS `container.alias`). */
   #aliases: Map<string, ServiceToken> = new Map()
+  /** parent class → (binding key → the factory that class gets instead). */
+  #contextualBindings: Map<new (...args: never[]) => unknown, Map<string, ServiceFactory>> =
+    new Map()
   /** token key → post-resolution callbacks (AdonisJS `container.resolving`). */
   #resolvingHooks: Map<string, Array<(value: unknown) => void | Promise<void>>> = new Map()
   /**
@@ -81,6 +127,33 @@ export class Container {
     this.#bindings.set(key, { token, factory: () => value, scope: 'singleton', dependencies: [] })
   }
 
+  /**
+   * Give ONE class a different implementation of a dependency (AdonisJS
+   * `container.contextualBinding`).
+   *
+   * `contextualBinding(UsersController, Hash, () => new Argon2())` — everyone
+   * else asking for `Hash` still gets the container's binding. See
+   * {@link when} for the fluent spelling.
+   */
+  contextualBinding(
+    parent: new (...args: never[]) => unknown,
+    binding: ServiceToken,
+    factory: ServiceFactory,
+  ): void {
+    const forParent = this.#contextualBindings.get(parent) ?? new Map()
+    forParent.set(this.#tokenToKey(binding), factory)
+    this.#contextualBindings.set(parent, forParent)
+  }
+
+  /**
+   * Fluent contextual binding (AdonisJS `container.when`):
+   *
+   *     container.when(UsersController).asksFor(Hash).provide(() => new Argon2())
+   */
+  when(parent: new (...args: never[]) => unknown): ContextualBindingsBuilder {
+    return new ContextualBindingsBuilder(this, parent)
+  }
+
   /**
    * Register an alias — resolving `alias` forwards to `target` (AdonisJS
    * `container.alias('db', Database)`). The target may be a class, string, or
@@ -176,11 +249,30 @@ export class Container {
    * res])`); only the `undefined` slots are container-resolved, top-level only.
    */
   async resolve<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
-    // Dereference an alias to its target before anything else.
-    const aliasTarget = this.#aliases.get(this.#tokenToKey(token))
-    if (aliasTarget !== undefined) return this.resolve<T>(aliasTarget, runtimeValues)
-
-    const key = this.#tokenToKey(token)
+    // Dereference aliases to the final target before anything else. Walked in
+    // a LOOP with its own seen-set: recursing into `resolve()` re-entered
+    // before the cycle guard below was armed, so `alias('a','b')` +
+    // `alias('b','a')` overflowed the stack instead of naming the cycle.
+    let resolvedToken = token
+    let key = this.#tokenToKey(resolvedToken)
+    const seenAliases = new Set<string>([key])
+    for (
+      let target = this.#aliases.get(key);
+      target !== undefined;
+      target = this.#aliases.get(key)
+    ) {
+      resolvedToken = target
+      key = this.#tokenToKey(target)
+      if (seenAliases.has(key)) {
+        const cycle = [...seenAliases, key].join(' → ')
+        throw new ReamError('CIRCULAR_DEPENDENCY', `Circular alias detected: ${cycle}`, {
+          hint: 'An alias chain must end at a real binding — remove one of the aliases.',
+          context: { chain: cycle },
+        })
+      }
+      seenAliases.add(key)
+    }
+    token = resolvedToken
 
     // Top of a chain: open one, so everything this resolution triggers shares
     // it and nothing outside it does.
@@ -219,10 +311,23 @@ export class Container {
     method: K,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
-    type Ctor = new (...args: unknown[]) => unknown
+    type Ctor = new (...args: never[]) => unknown
     // `Object.getPrototypeOf` is typed `any` in lib.dom, so the assignment
     // narrows it back to a typed constructor without a cast expression.
     const target: Ctor = Object.getPrototypeOf(instance).constructor
+    // A method's dependencies are dependencies of the class declaring it, so a
+    // contextual binding applies to `call()` exactly as to a constructor. There
+    // is usually no chain open here — `call()` is an entry point — so one is
+    // opened to carry the parent, rather than each `resolve()` below opening
+    // its own with nobody in it.
+    const chain = this.#chain.getStore()
+    if (chain === undefined) {
+      return this.#chain.run({ stack: [], set: new Set(), parent: target }, () =>
+        this.call(instance, method, runtimeValues),
+      )
+    }
+    const outerParent = chain.parent
+    chain.parent = target
     const paramTypes: unknown[] =
       Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
     // `@Inject('token')` on a method parameter — a named binding the reflected
@@ -252,6 +357,8 @@ export class Container {
       args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
     }
 
+    chain.parent = outerParent
+
     const member: unknown = instance[method]
     if (!isCallable(member)) {
       throw new Error(`Container.call: '${method}' is not a callable method`)
@@ -259,6 +366,55 @@ export class Container {
     return member.apply(instance, args)
   }
 
+  /**
+   * A resolver whose {@link ContainerResolver.bindValue} values are isolated
+   * from this container (AdonisJS `container.createResolver()`).
+   *
+   * Anything the resolver builds — and everything that build depends on — sees
+   * those values; nothing outside it does. This is how a request binds its own
+   * `HttpContext` without every other request seeing it.
+   */
+  createResolver(): ContainerResolver {
+    return new ContainerResolver(this)
+  }
+
+  /**
+   * @internal Run `fn` with `values` layered onto the resolution chain.
+   *
+   * Reuses an open chain rather than starting a second one, so cycle detection
+   * still spans the whole resolution when a resolver is used inside a factory.
+   */
+  runWithScopedValues<T>(values: ReadonlyMap<string, unknown>, fn: () => Promise<T>): Promise<T> {
+    const chain = this.#chain.getStore()
+    return this.#chain.run(
+      chain === undefined ? { stack: [], set: new Set(), values } : { ...chain, values },
+      fn,
+    )
+  }
+
+  /** @internal Normalise a token the way the container keys it. */
+  keyFor(token: ServiceToken): string {
+    return this.#tokenToKey(token)
+  }
+
+  /**
+   * Resolve `token` as if `parent` had asked for it, so `parent`'s contextual
+   * bindings apply (AdonisJS `resolveFor`). `parent: null` means nobody asked —
+   * identical to {@link make}.
+   */
+  async resolveFor<T>(
+    parent: (new (...args: never[]) => unknown) | null,
+    token: ServiceToken,
+    runtimeValues?: unknown[],
+  ): Promise<T> {
+    if (parent === null) return this.make<T>(token, runtimeValues)
+    const chain = this.#chain.getStore()
+    return this.#chain.run(
+      chain === undefined ? { stack: [], set: new Set(), parent } : { ...chain, parent },
+      () => this.make<T>(token, runtimeValues),
+    )
+  }
+
   // ─── Introspection ────────────────────────────────────────
 
   /** Check if a token is registered or resolvable. */
@@ -307,31 +463,74 @@ export class Container {
       return swapped as T
     }
 
-    // 2. Check cached singletons
+    // 2. A contextual binding for the class currently being built — "when
+    //    UsersController asks for Hash, give it Argon2". Before the resolver's
+    //    values and the container's, after swaps: @adonisjs/fold's order.
+    const store = this.#chain.getStore()
+    const contextual =
+      store?.parent === undefined ? undefined : this.#contextualBindings.get(store.parent)?.get(key)
+    if (contextual !== undefined) {
+      const instance = await contextual(this)
+      await this.#runResolvingHooks(key, instance)
+      return instance as T
+    }
+
+    // 3. A value bound on the resolver that opened this chain. Before the
+    //    container's own values, after swaps — the order @adonisjs/fold
+    //    resolves in (`resolveFor`: swaps, resolver values, container values).
+    //    No `resolving` hooks: the value was not constructed here.
+    if (store?.values?.has(key)) {
+      store.scopedReads = (store.scopedReads ?? 0) + 1
+      return store.values.get(key) as T
+    }
+
+    // 4. Check cached singletons
     if (this.#singletons.has(key)) {
       return this.#singletons.get(key) as T
     }
 
-    // 3. Check explicit bindings — the factory may be async.
+    // 5. Check explicit bindings — the factory may be async.
     const binding = this.#bindings.get(key)
     if (binding) {
-      const instance = binding.factory ? await binding.factory(this) : undefined
-      if (binding.scope === 'singleton') {
-        this.#singletons.set(key, instance)
+      if (binding.scope !== 'singleton') {
+        const instance = binding.factory ? await binding.factory(this) : undefined
+        await this.#runResolvingHooks(key, instance)
+        // Boundary cast from `unknown` — the caller brands the resolved type via T.
+        return instance as T
+      }
+
+      // A build already under way: join it rather than start a second one.
+      const inFlight = this.#pendingSingletons.get(key)
+      if (inFlight) return (await inFlight) as T
+
+      const readsBefore = store?.scopedReads ?? 0
+      const building = (async (): Promise<unknown> => {
+        const instance = binding.factory ? await binding.factory(this) : undefined
+        // See `ResolutionChain.scopedReads`: a build that consumed a
+        // request-scoped value is that request's, not the application's.
+        this.#cacheIfAppWide('singleton', key, instance, store, readsBefore)
+        // Inside the promise, so the hooks run exactly once per instance no
+        // matter how many callers were waiting.
+        await this.#runResolvingHooks(key, instance)
+        return instance
+      })()
+      this.#pendingSingletons.set(key, building)
+      try {
+        return (await building) as T
+      } finally {
+        // Cleared either way: a failed build must not poison later attempts.
+        this.#pendingSingletons.delete(key)
       }
-      await this.#runResolvingHooks(key, instance)
-      // Boundary cast from `unknown` — the caller brands the resolved type via T.
-      return instance as T
     }
 
-    // 4. Auto-construct if it's a class
+    // 6. Auto-construct if it's a class
     if (typeof token === 'function') {
       const instance = (await this.#autoConstruct(token, runtimeValues)) as T
       await this.#runResolvingHooks(key, instance)
       return instance
     }
 
-    // 5. Not found
+    // 7. Not found
     const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()]
     const suggestion = didYouMean(key, allKeys)
     throw new ReamError(
@@ -352,7 +551,24 @@ export class Container {
    * 3. No params → plain `new Class()`
    */
   async #autoConstruct(
-    target: new (...args: unknown[]) => unknown,
+    target: new (...args: never[]) => unknown,
+    runtimeValues?: unknown[],
+  ): Promise<unknown> {
+    // Everything resolved inside is a dependency OF `target`, which is what a
+    // contextual binding keys on. Restored on EVERY exit — the construction has
+    // three returns and can throw — so `target`'s own parent is back in place.
+    const store = this.#chain.getStore()
+    const outerParent = store?.parent
+    if (store !== undefined) store.parent = target
+    try {
+      return await this.#constructWithDeps(target, runtimeValues)
+    } finally {
+      if (store !== undefined) store.parent = outerParent
+    }
+  }
+
+  async #constructWithDeps(
+    target: new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
     const metadata = getServiceMetadata(target)
@@ -363,6 +579,10 @@ export class Container {
       return this.#singletons.get(key)
     }
 
+    // Same rule as the explicit singleton bindings: see `scopedReads`.
+    const store = this.#chain.getStore()
+    const readsBefore = store?.scopedReads ?? 0
+
     // A runtime value at this index (from `make(Class, [req, res])`) wins over
     // container resolution for that constructor slot.
     const runtimeAt = (index: number): unknown => runtimeValues?.[index]
@@ -397,8 +617,8 @@ export class Container {
           const depToken = injectTokens.get(index)
           deps.push(depToken ? await this.resolve(depToken) : undefined)
         }
-        const instance = new target(...deps)
-        if (scope === 'singleton') this.#singletons.set(key, instance)
+        const instance = Reflect.construct(target, deps)
+        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (b) No @Inject/metadata, but the caller supplied runtime values — build
@@ -406,8 +626,8 @@ export class Container {
       //     constructor). Slots beyond the runtime values stay undefined.
       if (target.length > 0 && (runtimeValues?.length ?? 0) > 0) {
         const deps = Array.from({ length: target.length }, (_value, index) => runtimeAt(index))
-        const instance = new target(...deps)
-        if (scope === 'singleton') this.#singletons.set(key, instance)
+        const instance = Reflect.construct(target, deps)
+        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (c) The constructor declares parameters but we have no way to resolve
@@ -424,7 +644,7 @@ export class Container {
       }
       // (d) Genuine zero-argument class.
       const instance = new target()
-      if (scope === 'singleton') this.#singletons.set(key, instance)
+      this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
       return instance
     }
 
@@ -446,11 +666,31 @@ export class Container {
       deps.push(depToken ? await this.resolve(depToken) : undefined)
     }
 
-    const instance = new target(...deps)
-    if (scope === 'singleton') this.#singletons.set(key, instance)
+    const instance = Reflect.construct(target, deps)
+    this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
     return instance
   }
 
+  /**
+   * Cache a singleton — unless it read a request-scoped value while building.
+   *
+   * See `ResolutionChain.scopedReads`: an instance that captured one belongs to
+   * that request, and caching it hands the first request's state to every
+   * later one. AdonisJS does not guard this; it is the kind of silent
+   * cross-request leak worth refusing.
+   */
+  #cacheIfAppWide(
+    scope: string,
+    key: string,
+    instance: unknown,
+    store: ResolutionChain | undefined,
+    readsBefore: number,
+  ): void {
+    if (scope !== 'singleton') return
+    if ((store?.scopedReads ?? 0) !== readsBefore) return
+    this.#singletons.set(key, instance)
+  }
+
   #tokenToKey(token: ServiceToken): string {
     if (typeof token === 'string') {
       this.#assertNotReserved(token, 'string')
@@ -507,7 +747,7 @@ const NON_INJECTABLE_CONSTRUCTORS = new Set<unknown>([
 ])
 
 /** True for a real, injectable class token (excludes native primitive constructors). */
-function isInjectableClass(value: unknown): value is new (...args: unknown[]) => unknown {
+function isInjectableClass(value: unknown): value is new (...args: never[]) => unknown {
   return typeof value === 'function' && !NON_INJECTABLE_CONSTRUCTORS.has(value)
 }
 

package/src/container/ContainerResolver.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-request view of the {@link Container} — AdonisJS Fold's
+ * `ContainerResolver`.
+ *
+ * A resolver resolves exactly what the container resolves, plus the values
+ * bound on it with {@link ContainerResolver.bindValue}. Those values are
+ * ISOLATED: they are visible to everything this resolver builds, including the
+ * constructor dependencies of what it builds, and to nothing else. That is what
+ * makes it safe for the HTTP kernel to bind one request's `HttpContext` — on
+ * the container itself, the binding would leak into every other request.
+ *
+ *     const resolver = container.createResolver()
+ *     resolver.bindValue(HttpContext, ctx)
+ *     await resolver.make(UsersController) // gets this request's ctx
+ */
+
+import type { Container } from './Container.js'
+import type { ServiceToken } from './types.js'
+
+export class ContainerResolver {
+  readonly #container: Container
+  /** Values bound here, keyed the way the container keys its tokens. */
+  readonly #values = new Map<string, unknown>()
+
+  constructor(container: Container) {
+    this.#container = container
+  }
+
+  /**
+   * Bind a resolved value for this resolver only (AdonisJS
+   * `resolver.bindValue`). Rebinding the same token replaces it.
+   */
+  bindValue<T>(token: ServiceToken, value: T): void {
+    this.#values.set(this.#container.keyFor(token), value)
+  }
+
+  /**
+   * Resolve a token, seeing this resolver's values first (AdonisJS
+   * `resolver.make`).
+   */
+  make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
+    return this.#container.runWithScopedValues(this.#values, () =>
+      this.#container.make<T>(token, runtimeValues),
+    )
+  }
+
+  /**
+   * Call a method with its dependencies injected, seeing this resolver's
+   * values (AdonisJS `resolver.call`).
+   */
+  call<T, K extends string & keyof T>(
+    instance: T,
+    method: K,
+    runtimeValues?: unknown[],
+  ): Promise<unknown> {
+    return this.#container.runWithScopedValues(this.#values, () =>
+      this.#container.call(instance, method, runtimeValues),
+    )
+  }
+
+  /**
+   * Resolve as if `parent` had asked, so `parent`'s contextual bindings apply
+   * (AdonisJS `resolver.resolveFor`). `null` means nobody asked.
+   */
+  resolveFor<T>(
+    parent: (new (...args: never[]) => unknown) | null,
+    token: ServiceToken,
+    runtimeValues?: unknown[],
+  ): Promise<T> {
+    return this.#container.runWithScopedValues(this.#values, () =>
+      this.#container.resolveFor<T>(parent, token, runtimeValues),
+    )
+  }
+
+  /** Whether the token resolves — here or on the container (AdonisJS `hasBinding`). */
+  hasBinding(token: ServiceToken): boolean {
+    return this.#values.has(this.#container.keyFor(token)) || this.#container.has(token)
+  }
+
+  /** Whether every token resolves (AdonisJS `hasAllBindings`). */
+  hasAllBindings(tokens: ServiceToken[]): boolean {
+    return tokens.every((token) => this.hasBinding(token))
+  }
+}

package/src/container/ContextualBindingsBuilder.ts

@@ -0,0 +1,41 @@
+/**
+ * The fluent form of a contextual binding — AdonisJS `container.when()`.
+ *
+ *     container.when(UsersController).asksFor(Hash).provide(() => new Argon2())
+ *
+ * Reads as the sentence it is: when THIS class asks for THAT, give it this.
+ * `container.contextualBinding(parent, binding, factory)` is the same thing in
+ * one call.
+ */
+
+import type { Container } from './Container.js'
+import type { ServiceFactory, ServiceToken } from './types.js'
+
+export class ContextualBindingsBuilder {
+  readonly #container: Container
+  readonly #parent: new (
+    ...args: never[]
+  ) => unknown
+  #binding: ServiceToken | undefined
+
+  constructor(container: Container, parent: new (...args: never[]) => unknown) {
+    this.#container = container
+    this.#parent = parent
+  }
+
+  /** The dependency this class asks for. */
+  asksFor(binding: ServiceToken): this {
+    this.#binding = binding
+    return this
+  }
+
+  /** What it gets instead. */
+  provide(factory: ServiceFactory): void {
+    if (this.#binding === undefined) {
+      throw new Error(
+        'Container.when(): call asksFor(binding) before provide() — a contextual binding needs to know which dependency it replaces.',
+      )
+    }
+    this.#container.contextualBinding(this.#parent, this.#binding, factory)
+  }
+}

package/src/container/types.ts

@@ -14,24 +14,28 @@ export interface ServiceMetadata {
 }
 
 /** Token used to resolve a service — class constructor, string name, or registered symbol. */
-// biome-ignore lint/suspicious/noExplicitAny: IoC container tokens must accept any constructor signature
-export type ServiceToken = (new (...args: any[]) => unknown) | string | symbol
+// `never[]` accepts every constructor shape — parameters are contravariant, so
+// a rest of `never` is assignable from any concrete list.
+export type ServiceToken = (new (...args: never[]) => unknown) | string | symbol
 
 /**
- * Resolver handed to a binding factory so it can resolve its own dependencies
+ * What a binding factory is handed so it can resolve its own dependencies
  * (AdonisJS parity: `container.singleton(token, async (resolver) =>
- * await resolver.make(Dep))`). The Container itself satisfies this contract.
+ * await resolver.make(Dep))`).
+ *
+ * Narrow on purpose: both the `Container` and a per-request `ContainerResolver`
+ * satisfy it, so a factory works the same whichever one is resolving.
  */
-export interface ContainerResolver {
+export interface FactoryResolver {
   make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T>
 }
 
 /**
  * Factory function for creating service instances. Receives a {@link
- * ContainerResolver} (AdonisJS parity) — the async container means a factory
+ * FactoryResolver} (AdonisJS parity) — the async container means a factory
  * that needs another binding must `await resolver.make(Dep)`.
  */
-export type ServiceFactory = (resolver: ContainerResolver) => unknown
+export type ServiceFactory = (resolver: FactoryResolver) => unknown
 
 /** Binding entry in the container. */
 export interface Binding {

package/src/decorators/Service.ts

@@ -11,7 +11,10 @@ const SERVICE_METADATA_KEY = Symbol('ream:service')
 const INJECT_METADATA_KEY = Symbol('ream:inject')
 
 /** Constructor type — accepts unknown args, returns unknown instance. */
-type AnyConstructor = new (...args: unknown[]) => unknown
+// `never[]` accepts every constructor shape: parameters are contravariant, so a
+// rest of `never` is assignable from any concrete list. Same spelling as the
+// router's, so a class flows between the two without an assertion.
+type AnyConstructor = new (...args: never[]) => unknown
 
 /** Registry of all decorated services. */
 const serviceRegistry: Map<AnyConstructor, ServiceMetadata> = new Map()
@@ -33,14 +36,24 @@ export function getServiceMetadata(target: AnyConstructor): ServiceMetadata | un
  * @Service() decorator.
  * Registers the class in the IoC container for auto-resolution.
  */
+/** Anything with a construct signature — a decorated class always is. */
+function isConstructor(value: unknown): value is AnyConstructor {
+  return typeof value === 'function' && value.prototype !== undefined
+}
+
 export function Service(options: { scope?: ServiceScope; as?: string } = {}): ClassDecorator {
   return (target) => {
     const metadata: ServiceMetadata = {
       scope: options.scope ?? 'singleton',
       as: options.as,
     }
-    // biome-ignore lint/suspicious/noExplicitAny: ClassDecorator target is Function; registry requires AnyConstructor which is a subtype
-    serviceRegistry.set(target as any as AnyConstructor, metadata)
+    // A ClassDecorator's target is typed `Function`, which carries no
+    // construct signature; the guard is what states that a decorated class IS
+    // constructible.
+    if (!isConstructor(target)) {
+      throw new TypeError('@Service() can only decorate a class')
+    }
+    serviceRegistry.set(target, metadata)
     Reflect.defineMetadata(SERVICE_METADATA_KEY, metadata, target)
   }
 }