@c9up/ream 0.1.25 → 0.1.27

package/src/container/Container.ts

@@ -10,8 +10,13 @@
  */
 
 import 'reflect-metadata'
-import { createLazyProxy, getLazyParams } from '../decorators/Lazy.js'
-import { getInjectTokens, getServiceMetadata, getServiceRegistry } from '../decorators/Service.js'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  getInjectTokens,
+  getMethodInjectTokens,
+  getServiceMetadata,
+  getServiceRegistry,
+} from '../decorators/Service.js'
 import { didYouMean } from '../errors/FuzzyMatcher.js'
 import { ReamError } from '../errors/ReamError.js'
 import type { Binding, ServiceFactory, ServiceToken } from './types.js'
@@ -23,6 +28,12 @@ import type { Binding, ServiceFactory, ServiceToken } from './types.js'
  */
 const RESERVED_TOKEN_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
 
+/** One resolution chain: the tokens on it, and a set for O(1) membership. */
+interface ResolutionChain {
+  stack: string[]
+  set: Set<string>
+}
+
 export class Container {
   #bindings: Map<string, Binding> = new Map()
   #singletons: Map<string, unknown> = new Map()
@@ -34,8 +45,20 @@ export class Container {
    * pointing at the same object after the test ends.
    */
   #singletonBackup: Map<string, unknown> = new Map()
-  #resolutionStack: string[] = []
-  #resolutionSet: Set<string> = new Set()
+  /** Alias key → the token it forwards to (AdonisJS `container.alias`). */
+  #aliases: Map<string, ServiceToken> = new Map()
+  /** token key → post-resolution callbacks (AdonisJS `container.resolving`). */
+  #resolvingHooks: Map<string, Array<(value: unknown) => void | Promise<void>>> = new Map()
+  /**
+   * The resolution chain currently being walked, for cycle detection.
+   *
+   * Scoped to the async context, NOT to the container: `resolve()` is async, so
+   * two independent chains interleave, and a stack held on the instance would
+   * splice them together and report a cycle neither of them has. Per-container
+   * storage keeps a chain that crosses two containers from colliding on a token
+   * name they happen to share.
+   */
+  readonly #chain = new AsyncLocalStorage<ResolutionChain>()
 
   // ─── Explicit bindings ────────────────────────────────────
 
@@ -58,6 +81,33 @@ export class Container {
     this.#bindings.set(key, { token, factory: () => value, scope: 'singleton', dependencies: [] })
   }
 
+  /**
+   * Register an alias — resolving `alias` forwards to `target` (AdonisJS
+   * `container.alias('db', Database)`). The target may be a class, string, or
+   * symbol that itself resolves to a binding or an auto-constructable class.
+   */
+  alias(alias: ServiceToken, target: ServiceToken): void {
+    this.#aliases.set(this.#tokenToKey(alias), target)
+  }
+
+  /**
+   * Register a callback that runs each time `token` is constructed (AdonisJS
+   * `container.resolving`) — for lazy init (`db.connect()`) or decorating the
+   * resolved instance. Runs after construction of a binding/auto-constructed
+   * class; NOT for raw `bindValue` values or an already-cached singleton.
+   */
+  resolving(token: ServiceToken, callback: (value: unknown) => void | Promise<void>): void {
+    const key = this.#tokenToKey(token)
+    const hooks = this.#resolvingHooks.get(key)
+    if (hooks) hooks.push(callback)
+    else this.#resolvingHooks.set(key, [callback])
+  }
+
+  async #runResolvingHooks(key: string, value: unknown): Promise<void> {
+    const hooks = this.#resolvingHooks.get(key)
+    if (hooks) for (const hook of hooks) await hook(value)
+  }
+
   // ─── Testing ──────────────────────────────────────────────
 
   /**
@@ -115,29 +165,47 @@ export class Container {
    * 4. Auto-construct if class has @inject() or @Service()
    * 5. Auto-construct any class (plain `new Class()`) as fallback
    */
-  make<T>(token: ServiceToken): T {
-    return this.resolve<T>(token)
+  make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
+    return this.resolve<T>(token, runtimeValues)
   }
 
-  /** Alias for make() — backward compatible. */
-  resolve<T>(token: ServiceToken): T {
+  /**
+   * Resolve/construct a class or binding (AdonisJS `container.make` — async, so
+   * factories, providers and `resolving` hooks may be async). `runtimeValues`
+   * fill the resolved class's constructor slots by index (`make(Class, [req,
+   * 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)
 
-    if (this.#resolutionSet.has(key)) {
-      const cycle = [...this.#resolutionStack, key].join(' → ')
+    // Top of a chain: open one, so everything this resolution triggers shares
+    // it and nothing outside it does.
+    const chain = this.#chain.getStore()
+    if (chain === undefined) {
+      return this.#chain.run({ stack: [], set: new Set() }, () =>
+        this.resolve<T>(token, runtimeValues),
+      )
+    }
+
+    if (chain.set.has(key)) {
+      const cycle = [...chain.stack, key].join(' → ')
       throw new ReamError('CIRCULAR_DEPENDENCY', `Circular dependency detected: ${cycle}`, {
-        hint: 'Use @Lazy() on one of the constructor parameters to break the cycle.',
+        hint: 'Break the cycle by resolving one dependency lazily inside a method (`await container.make(Dep)`) instead of injecting it in the constructor.',
         context: { chain: cycle },
       })
     }
-    this.#resolutionStack.push(key)
-    this.#resolutionSet.add(key)
+    chain.stack.push(key)
+    chain.set.add(key)
 
     try {
-      return this.#resolveInner<T>(key, token)
+      return await this.#resolveInner<T>(key, token, runtimeValues)
     } finally {
-      this.#resolutionStack.pop()
-      this.#resolutionSet.delete(key)
+      chain.stack.pop()
+      chain.set.delete(key)
     }
   }
 
@@ -157,15 +225,32 @@ export class Container {
     const target: Ctor = Object.getPrototypeOf(instance).constructor
     const paramTypes: unknown[] =
       Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
-
-    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0)
-    const args = Array.from({ length: len }, (_, index) => {
-      // Runtime values take precedence (and fill slots beyond paramTypes)
-      if (runtimeValues && index < runtimeValues.length) return runtimeValues[index]
+    // `@Inject('token')` on a method parameter — a named binding the reflected
+    // type cannot express (an interface, or a class registered under a name).
+    const injectTokens = getMethodInjectTokens(target.prototype, method)
+
+    // `@Inject` counts towards the parameter span too: a method may carry named
+    // tokens without `design:paramtypes` being emitted for it, and computing the
+    // span from the reflected types alone left the loop at zero iterations —
+    // the tokens were read and then never used.
+    const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
+    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
+    // Sequential resolution keeps the shared cycle-detection stack consistent.
+    const args: unknown[] = []
+    for (let index = 0; index < len; index += 1) {
+      // Runtime values take precedence (and fill slots beyond paramTypes).
+      if (runtimeValues && index < runtimeValues.length) {
+        args.push(runtimeValues[index])
+        continue
+      }
+      const named = injectTokens.get(index)
+      if (named !== undefined) {
+        args.push(await this.resolve(named))
+        continue
+      }
       const type = paramTypes[index]
-      if (isClassConstructor(type)) return this.resolve(type)
-      return undefined
-    })
+      args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
+    }
 
     const member: unknown = instance[method]
     if (!isCallable(member)) {
@@ -183,10 +268,16 @@ export class Container {
       this.#bindings.has(key) ||
       this.#overrides.has(key) ||
       this.#singletons.has(key) ||
+      this.#aliases.has(key) ||
       (typeof token === 'function' && getServiceMetadata(token) !== undefined)
     )
   }
 
+  /** True only when EVERY token is registered/resolvable (AdonisJS `hasAllBindings`). */
+  hasAllBindings(tokens: ServiceToken[]): boolean {
+    return tokens.every((token) => this.has(token))
+  }
+
   get size(): number {
     return this.#bindings.size
   }
@@ -209,34 +300,35 @@ export class Container {
 
   // ─── Internal resolution ──────────────────────────────────
 
-  #resolveInner<T>(key: string, token: ServiceToken): T {
-    // 1. Check swaps (test overrides)
+  async #resolveInner<T>(key: string, token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
+    // 1. Check swaps (test overrides) — a swap factory may be async.
     if (this.#overrides.has(key)) {
-      // biome-ignore lint/suspicious/noExplicitAny: IoC container factory returns unknown; caller brands via T
-      return this.#overrides.get(key)?.() as any as T
+      const swapped = await this.#overrides.get(key)?.(this)
+      return swapped as T
     }
 
     // 2. Check cached singletons
     if (this.#singletons.has(key)) {
-      // biome-ignore lint/suspicious/noExplicitAny: IoC singleton stored as unknown; caller brands via T
-      return this.#singletons.get(key) as any as T
+      return this.#singletons.get(key) as T
     }
 
-    // 3. Check explicit bindings
+    // 3. Check explicit bindings — the factory may be async.
     const binding = this.#bindings.get(key)
     if (binding) {
-      const instance = binding.factory ? binding.factory() : undefined
+      const instance = binding.factory ? await binding.factory(this) : undefined
       if (binding.scope === 'singleton') {
         this.#singletons.set(key, instance)
       }
-      // biome-ignore lint/suspicious/noExplicitAny: IoC binding factory returns unknown; caller brands via T
-      return instance as any as T
+      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
     if (typeof token === 'function') {
-      // biome-ignore lint/suspicious/noExplicitAny: IoC auto-construct returns unknown; caller brands via T
-      return this.#autoConstruct(token) as any as T
+      const instance = (await this.#autoConstruct(token, runtimeValues)) as T
+      await this.#runResolvingHooks(key, instance)
+      return instance
     }
 
     // 5. Not found
@@ -259,7 +351,10 @@ export class Container {
    * 2. Reflect.getMetadata('design:paramtypes') — decorator metadata (requires SWC/tsc)
    * 3. No params → plain `new Class()`
    */
-  #autoConstruct(target: new (...args: unknown[]) => unknown): unknown {
+  async #autoConstruct(
+    target: new (...args: unknown[]) => unknown,
+    runtimeValues?: unknown[],
+  ): Promise<unknown> {
     const metadata = getServiceMetadata(target)
     const scope = metadata?.scope ?? 'transient'
     const key = metadata?.as ?? target.name
@@ -268,10 +363,12 @@ export class Container {
       return this.#singletons.get(key)
     }
 
+    // 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]
+
     // 1. Check static containerInjections (AdonisJS Fold-compatible, works
-    // without emitDecoratorMetadata). The `in` operator narrows the optional
-    // field to `unknown`, then `readContainerInjectionDeps` validates the
-    // shape at runtime — no type-level cast required.
+    // without emitDecoratorMetadata).
     const explicitDeps = readContainerInjectionDeps(target)
 
     // 2. Fallback to reflect-metadata
@@ -279,7 +376,6 @@ export class Container {
       explicitDeps ?? Reflect.getMetadata('design:paramtypes', target) ?? []
 
     const injectTokens = getInjectTokens(target)
-    const lazyIndices = getLazyParams(target)
 
     // No `design:paramtypes` (a dev transpiler may not emit decorator metadata —
     // esbuild / tsx don't). Recover what we can, and NEVER construct with
@@ -287,22 +383,34 @@ export class Container {
     if (paramTypes.length === 0) {
       // (a) `@Inject(token)` records its tokens INDEPENDENTLY of decorator
       //     metadata, so even without `design:paramtypes` we can resolve the
-      //     constructor from that map alone.
+      //     constructor from that map alone. Deps resolve SEQUENTIALLY so the
+      //     shared cycle-detection stack stays consistent.
       if (injectTokens.size > 0) {
-        const maxIndex = Math.max(...injectTokens.keys())
-        const deps = Array.from({ length: maxIndex + 1 }, (_value, index) => {
-          const depToken = injectTokens.get(index)
-          if (!depToken) return undefined
-          if (lazyIndices.includes(index)) {
-            return createLazyProxy(() => this.resolve<object>(depToken))
+        const maxIndex = Math.max(...injectTokens.keys(), (runtimeValues?.length ?? 0) - 1)
+        const deps: unknown[] = []
+        for (let index = 0; index <= maxIndex; index += 1) {
+          const rt = runtimeAt(index)
+          if (rt !== undefined) {
+            deps.push(rt)
+            continue
           }
-          return this.resolve(depToken)
-        })
+          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)
         return instance
       }
-      // (b) The constructor declares parameters but we have no way to resolve
+      // (b) No @Inject/metadata, but the caller supplied runtime values — build
+      //     from those (the `make(Controller, [req, res])` pattern with a plain
+      //     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)
+        return instance
+      }
+      // (c) The constructor declares parameters but we have no way to resolve
       //     them (no metadata, no @Inject, no containerInjections). Fail LOUDLY
       //     instead of `new target()` with undefined deps.
       if (target.length > 0) {
@@ -314,29 +422,29 @@ export class Container {
           },
         )
       }
-      // (c) Genuine zero-argument class.
+      // (d) Genuine zero-argument class.
       const instance = new target()
       if (scope === 'singleton') this.#singletons.set(key, instance)
       return instance
     }
 
-    const deps = paramTypes.map((type, index) => {
+    // Resolve constructor deps SEQUENTIALLY (the cycle-detection stack is
+    // instance-shared, so parallel Promise.all would interleave and corrupt it).
+    const deps: unknown[] = []
+    for (let index = 0; index < paramTypes.length; index += 1) {
+      const rt = runtimeAt(index)
+      if (rt !== undefined) {
+        deps.push(rt)
+        continue
+      }
       const namedToken = injectTokens.get(index)
-      // After the typeof check, type is a constructor function and valid as ServiceToken
+      const type = paramTypes[index]
+      // A native primitive constructor (String/Number/Boolean/…) is NOT
+      // injectable — leave the slot undefined so a constructor default can fill it.
       const depToken: ServiceToken | undefined =
-        namedToken ??
-        // biome-ignore lint/suspicious/noExplicitAny: reflect-metadata returns unknown; constructor functions are valid ServiceTokens
-        (typeof type === 'function' && type !== Object ? (type as any as ServiceToken) : undefined)
-
-      if (!depToken) return undefined
-
-      if (lazyIndices.includes(index)) {
-        // biome-ignore lint/suspicious/noExplicitAny: lazy proxy target must be object; IoC resolution returns unknown
-        return createLazyProxy(() => this.resolve(depToken) as any as object)
-      }
-
-      return this.resolve(depToken)
-    })
+        namedToken ?? (isInjectableClass(type) ? type : undefined)
+      deps.push(depToken ? await this.resolve(depToken) : undefined)
+    }
 
     const instance = new target(...deps)
     if (scope === 'singleton') this.#singletons.set(key, instance)
@@ -378,11 +486,29 @@ export class Container {
   }
 }
 
-// `design:paramtypes` returns `unknown[]` per our annotation; we narrow each
-// entry before treating it as a class token. `Object` slips through because
-// emitDecoratorMetadata uses it for `any`/`unknown` parameters.
-function isClassConstructor(value: unknown): value is new (...args: unknown[]) => unknown {
-  return typeof value === 'function' && value !== Object
+/**
+ * Native constructors emitDecoratorMetadata uses for primitive / `any` /
+ * `unknown` parameters. They are NOT injectable — resolving them would try to
+ * auto-construct `String`/`Number`/… (or silently inject `undefined`), so we
+ * skip them and let a constructor default fill the slot instead.
+ */
+const NON_INJECTABLE_CONSTRUCTORS = new Set<unknown>([
+  Object,
+  String,
+  Number,
+  Boolean,
+  Array,
+  Function,
+  Symbol,
+  Date,
+  RegExp,
+  Promise,
+  Error,
+])
+
+/** True for a real, injectable class token (excludes native primitive constructors). */
+function isInjectableClass(value: unknown): value is new (...args: unknown[]) => unknown {
+  return typeof value === 'function' && !NON_INJECTABLE_CONSTRUCTORS.has(value)
 }
 
 function isCallable(value: unknown): value is (...args: unknown[]) => unknown {

package/src/container/types.ts

@@ -17,8 +17,21 @@ export interface ServiceMetadata {
 // biome-ignore lint/suspicious/noExplicitAny: IoC container tokens must accept any constructor signature
 export type ServiceToken = (new (...args: any[]) => unknown) | string | symbol
 
-/** Factory function for creating service instances. */
-export type ServiceFactory = () => unknown
+/**
+ * Resolver handed to a binding factory so it can resolve its own dependencies
+ * (AdonisJS parity: `container.singleton(token, async (resolver) =>
+ * await resolver.make(Dep))`). The Container itself satisfies this contract.
+ */
+export interface ContainerResolver {
+  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
+ * that needs another binding must `await resolver.make(Dep)`.
+ */
+export type ServiceFactory = (resolver: ContainerResolver) => unknown
 
 /** Binding entry in the container. */
 export interface Binding {

package/src/decorators/Service.ts

@@ -51,11 +51,23 @@ export function Service(options: { scope?: ServiceScope; as?: string } = {}): Cl
  * @implements FR16
  */
 export function Inject(token: ServiceToken): ParameterDecorator {
-  return (target, _propertyKey, parameterIndex) => {
+  return (target, propertyKey, parameterIndex) => {
+    // A constructor parameter reports no property key and lands on the class;
+    // a method parameter lands on the prototype and MUST be keyed by method
+    // name, or every method of the class would share one map and overwrite
+    // each other's tokens.
     const existingTokens: Map<number, ServiceToken> =
-      Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
+      (propertyKey === undefined
+        ? Reflect.getOwnMetadata(INJECT_METADATA_KEY, target)
+        : Reflect.getOwnMetadata(INJECT_METADATA_KEY, target, propertyKey)) ?? new Map()
+
     existingTokens.set(parameterIndex, token)
-    Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target)
+
+    if (propertyKey === undefined) {
+      Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target)
+    } else {
+      Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target, propertyKey)
+    }
   }
 }
 
@@ -66,6 +78,19 @@ export function getInjectTokens(target: AnyConstructor): Map<number, ServiceToke
   return Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
 }
 
+/**
+ * Get named injection tokens for one method's parameters.
+ *
+ * `target` is the prototype carrying the method — that is where a parameter
+ * decorator on a method writes.
+ */
+export function getMethodInjectTokens(
+  target: object,
+  propertyKey: string | symbol,
+): Map<number, ServiceToken> {
+  return Reflect.getOwnMetadata(INJECT_METADATA_KEY, target, propertyKey) ?? new Map()
+}
+
 /**
  * @inject() class decorator — marks a controller (or service) for transient IoC resolution.
  *

package/src/env/Env.ts

@@ -1,3 +1,9 @@
+import {
+  defineIdentifier,
+  defineIdentifierIfMissing,
+  type IdentifierResolver,
+  removeIdentifier,
+} from './interpolate.js'
 import { loadEnvFiles } from './loadEnvFiles.js'
 import { type SchemaNode, schema } from './schema.js'
 
@@ -45,6 +51,21 @@ export class Env<Values extends Record<string, unknown>> {
   /** The validation schema surface — `Env.schema.string()`, `.number()`, … */
   static readonly schema = schema
 
+  /** Register an interpolation identifier (AdonisJS `Env.defineIdentifier`). */
+  static defineIdentifier(name: string, resolver: IdentifierResolver): void {
+    defineIdentifier(name, resolver)
+  }
+
+  /** Register an identifier only if the name is free (AdonisJS `defineIdentifierIfMissing`). */
+  static defineIdentifierIfMissing(name: string, resolver: IdentifierResolver): void {
+    defineIdentifierIfMissing(name, resolver)
+  }
+
+  /** Remove a registered interpolation identifier (AdonisJS `Env.removeIdentifier`). */
+  static removeIdentifier(name: string): void {
+    removeIdentifier(name)
+  }
+
   readonly #values: Values
 
   private constructor(values: Values) {
@@ -80,12 +101,35 @@ export class Env<Values extends Record<string, unknown>> {
     return new Env(collected as EnvRecord<S>)
   }
 
-  /** Read a validated variable. Required keys are always present; optional keys may be `undefined`. */
+  /**
+   * Read a variable. Validated keys are typed; for any other key the raw
+   * `process.env` value is returned as a fallback (AdonisJS `env.get`
+   * semantics). Required keys are always present; optional keys may be
+   * `undefined`. The second argument is the default when nothing is found.
+   */
   get<K extends keyof Values>(key: K): Values[K]
   get<K extends keyof Values>(key: K, fallback: Values[K]): Values[K]
-  get<K extends keyof Values>(key: K, fallback?: Values[K]): Values[K] {
-    const value = this.#values[key]
-    if (value === undefined && fallback !== undefined) return fallback
-    return value
+  get(key: string): string | undefined
+  get(key: string, fallback: string): string
+  get(key: string, fallback?: unknown): unknown {
+    const cached = this.#values[key]
+    if (cached !== undefined) return cached
+    // Fallback to raw process.env for keys outside the validated schema.
+    const fromEnv = process.env[key]
+    if (fromEnv !== undefined && fromEnv !== '') return fromEnv
+    return fallback
+  }
+
+  /**
+   * Set/override a variable at runtime (AdonisJS `env.set`). Updates the cache
+   * AND `process.env`. The value is NOT re-validated — pass the correct type.
+   */
+  set<K extends keyof Values>(key: K, value: Values[K]): void
+  set(key: string, value: string): void
+  set(key: string, value: unknown): void {
+    // Reflect.set writes to the generic-typed cache without a cast (a direct
+    // `this.#values[key] = value` is rejected: a generic type is read-only-indexed).
+    Reflect.set(this.#values, key, value)
+    process.env[key] = String(value)
   }
 }

package/src/env/Secret.ts

@@ -0,0 +1,41 @@
+/**
+ * Secret — wraps a sensitive value so it never leaks through logs, JSON, or
+ * `util.inspect`. Mirrors `@poppinss/utils`'s `Secret` (zero-dep here). Read the
+ * underlying value explicitly with {@link release}.
+ *
+ *   const key = env.get('APP_KEY')   // Secret<string> when declared via schema.secret
+ *   key.toString()   // '[redacted]'
+ *   JSON.stringify({ key })          // '{"key":"[redacted]"}'
+ *   key.release()    // the real value — only when you deliberately need it
+ */
+const REDACTED = '[redacted]'
+
+export class Secret<T> {
+  readonly #value: T
+  readonly #keyword: string
+
+  constructor(value: T, redactedKeyword: string = REDACTED) {
+    this.#value = value
+    this.#keyword = redactedKeyword
+  }
+
+  /** Redacted placeholder (so `JSON.stringify` never emits the secret). */
+  toJSON(): string {
+    return this.#keyword
+  }
+
+  /** Redacted placeholder for string coercion + template literals. */
+  toString(): string {
+    return this.#keyword
+  }
+
+  /** Redacted placeholder for `console.log` / `util.inspect`. */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.#keyword
+  }
+
+  /** Release the underlying value — the one deliberate way to read the secret. */
+  release(): T {
+    return this.#value
+  }
+}

package/src/env/interpolate.ts

@@ -0,0 +1,54 @@
+/**
+ * Env value interpolation — AdonisJS-style variable substitution + identifiers,
+ * applied by {@link loadEnvFiles} as each `.env` value is loaded.
+ *
+ * - `$VAR` / `${VAR}` are replaced with the value of `VAR` (looked up against
+ *   the values already loaded + `process.env`). A missing reference expands to
+ *   an empty string. `\$` is a literal dollar sign (escape).
+ * - `identifier:rest` — when `identifier` was registered via
+ *   {@link defineIdentifier}, the registered callback transforms `rest`
+ *   (e.g. a `base64:` decoder). Unregistered prefixes (like `postgres://…`)
+ *   are left untouched.
+ */
+
+/** Transform the remainder of an `identifier:rest` value into its final form. */
+export type IdentifierResolver = (value: string) => string
+
+const identifiers = new Map<string, IdentifierResolver>()
+
+/** Register an identifier resolver (AdonisJS `Env.defineIdentifier`). */
+export function defineIdentifier(name: string, resolver: IdentifierResolver): void {
+  identifiers.set(name, resolver)
+}
+
+/** Register an identifier resolver only if the name is free (AdonisJS `defineIdentifierIfMissing`). */
+export function defineIdentifierIfMissing(name: string, resolver: IdentifierResolver): void {
+  if (!identifiers.has(name)) identifiers.set(name, resolver)
+}
+
+/** Remove a registered identifier (AdonisJS `Env.removeIdentifier`). */
+export function removeIdentifier(name: string): void {
+  identifiers.delete(name)
+}
+
+const REFERENCE = /(\\)?\$(?:\{([^}]+)\}|([A-Za-z_][A-Za-z0-9_]*))/g
+
+/**
+ * Expand `$VAR` / `${VAR}` references and apply an identifier prefix. `lookup`
+ * resolves a referenced variable name to its current value (or undefined).
+ */
+export function interpolate(value: string, lookup: (name: string) => string | undefined): string {
+  const substituted = value.replace(REFERENCE, (full, escaped, braced, bare) => {
+    // `\$FOO` → literal `$FOO` (drop only the escaping backslash).
+    if (escaped) return full.slice(1)
+    const name = braced ?? bare
+    return lookup(name) ?? ''
+  })
+
+  const prefixed = /^([A-Za-z_][A-Za-z0-9_]*):([\s\S]*)$/.exec(substituted)
+  if (prefixed) {
+    const resolver = identifiers.get(prefixed[1])
+    if (resolver) return resolver(prefixed[2])
+  }
+  return substituted
+}