@cyrenex/pondi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+<h1 align="center">pondi</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">Drop a pebble, get a ripple. Type-safe, string-keyed dependency injection for TypeScript.</p>
+
+<p align="center">
+  [<a href="https://github.com/cyrenex/pondi/blob/master/README.zh-CN.md">简体中文</a>] [<a href="https://www.npmjs.com/package/@cyrenex/pondi">npm</a>]
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@cyrenex/pondi"><img src="https://img.shields.io/npm/v/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669"></a>
+  <a href="https://www.npmjs.com/package/@cyrenex/pondi"><img src="https://img.shields.io/npm/dm/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669"></a>
+  <a href="https://bundlephobia.com/package/@cyrenex/pondi"><img src="https://img.shields.io/bundlephobia/minzip/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669&label=minzip"></a>
+  <a href="https://github.com/cyrenex/pondi/blob/master/LICENSE"><img src="https://img.shields.io/github/license/cyrenex/pondi.svg?style=flat&colorA=080f12&colorB=1fa669"></a>
+</p>
+
+> [!NOTE]
+> No decorators, no `reflect-metadata`, no runtime dependencies. Just keys, factories, and types.
+
+Most DI containers in TypeScript lean on decorators and emitted metadata, and you pay for that with build configuration and a class-only style. pondi goes the other way: **a dependency is a string key with a type attached**. You declare what you need with a `pebble`, describe how to build it with a `ripple`, and let a `Pond` wire everything together.
+
+Think of it as dropping a pebble into a pond: the pebble names what you need, the ripple is what it becomes.
+
+## What's Special
+
+- **Inferred types everywhere**: factory parameters are inferred from the dependency list, and wrong orders or shapes fail at compile time.
+- **Async all the way**: async factories, async `init` hooks, and concurrent resolves that run each factory only once.
+- **Hierarchical ponds**: `fork()` a child to override providers for tests, requests, or tenants; only the affected singletons are rebuilt.
+- **Deterministic disposal**: works with `await using`; children first, then instances in reverse creation order.
+- **Helpful errors**: every `PondError` carries a `code` and the full dependency `path`.
+
+## Installation
+
+```bash
+pnpm add @cyrenex/pondi
+```
+
+## Quick Start
+
+```ts
+import { pebble, Pond, ripple } from "@cyrenex/pondi";
+
+interface AgentOptions {
+  url: string;
+}
+
+// A contract: a type, no implementation
+const AgentConfig = pebble<AgentOptions>("agent:config");
+
+// A plugin: provides an implementation for the contract
+const agentConfigPlugin = (options: AgentOptions) => ripple(AgentConfig, () => options);
+
+// A token with a default implementation
+const Message = ripple("message", () => "Hello, Pond!");
+
+// Declare dependencies; factory parameter types are inferred
+const Agent = ripple("agent", [Message, AgentConfig], async (message, config) => {
+  const connection = await connect(config.url);
+  return {
+    send: () => connection.send(message),
+    async [Symbol.asyncDispose]() {
+      await connection.close();
+    },
+  };
+});
+
+await using app = new Pond().use(agentConfigPlugin({ url: "ws://localhost" }));
+const agent = await app.resolve(Agent); // { send: () => void }
+```
+
+## Core Concepts
+
+| Concept     | Description                                                                    |
+| ----------- | ------------------------------------------------------------------------------ |
+| `pebble<T>` | A contract: a typed string key with no implementation                          |
+| `ripple`    | An implementation: key + dependencies + factory + mode; also usable as a token |
+| `Pond`      | The container: registers implementations, resolves instances, owns lifecycles  |
+
+**The key is the identity.** `ripple("message", ...)`, `pebble("message")`, and the string `"message"` all refer to the same token, so `app.resolve(Message)` and `app.resolve("message")` return the same instance. Namespace your keys to avoid collisions, e.g. `"agent:config"`.
+
+## Declaring Ripples
+
+```ts
+ripple(key, factory, options?)
+ripple(key, deps, factory, options?)
+ripple(pebble, factory, options?)        // implements a pebble; the return type must match the contract
+ripple(pebble, deps, factory, options?)
+```
+
+- `deps` may mix pebbles, ripples, and strings. The factory receives the resolved values in order.
+- Factories may be async. The container awaits them, so dependents always receive values, never promises.
+- `options.mode` defaults to `"singleton"`. See [Lifecycle Modes](#lifecycle-modes).
+
+### ripple.class
+
+Same signatures as `ripple`, but takes a class instead of a factory. Dependencies are passed to the constructor in order:
+
+```ts
+class Agent {
+  constructor(
+    readonly message: string,
+    readonly config: AgentOptions,
+  ) {}
+}
+
+const AgentRipple = ripple.class("agent", [Message, AgentConfig], Agent);
+const Logger = ripple.class(LoggerPebble, ConsoleLogger);
+```
+
+Constructor parameters are type-checked against the dependency list at compile time, so listing dependencies in the wrong order is an error.
+
+## Resolving and Types
+
+```ts
+await app.resolve(Agent); // typed by the ripple
+await app.resolve(AgentConfig); // typed by the pebble
+await app.resolve("message"); // typed by Registry, or unknown if not declared
+```
+
+To give plain string keys a type, augment `Registry`. Augmented keys get autocompletion, and `ripple` checks its return type against the declaration:
+
+```ts
+declare module "@cyrenex/pondi" {
+  interface Registry {
+    message: string;
+    "agent:config": AgentOptions;
+  }
+}
+```
+
+## Resolution Rules
+
+To resolve a token, the container looks for an implementation in this order:
+
+1. Implementations registered with `use` in the current container or any ancestor; the nearest one wins.
+2. If the token itself is a ripple, its own default implementation.
+3. Otherwise it throws `MISSING_PROVIDER`, with the full dependency path, e.g. `agent -> agent:config`.
+
+So a ripple can be resolved without calling `use` first. Pebbles and plain strings need some container to provide them.
+
+## Registering and Overriding
+
+### use
+
+```ts
+app.use(Message, agentConfigPlugin(opts), [PluginA, PluginB]); // arrays are accepted, so plugins can return several ripples
+```
+
+- Registering the same ripple object again has no effect.
+- Registering a different implementation for an existing key throws `DUPLICATE_PROVIDER`.
+- Once a key has been resolved, it can no longer be registered in that container or its ancestors (`PROVIDER_LOCKED`). This prevents old and new instances from coexisting.
+
+### fork
+
+There is one way to override an implementation: create a child container and register the same key in it.
+
+```ts
+await using test = app.fork().use(ripple("message", () => "mock"));
+
+await test.resolve(Agent); // uses the mocked message
+await app.resolve(Agent); // the parent is unaffected
+```
+
+In the child, **singletons affected by an override are rebuilt**, while unaffected singletons stay shared with the parent. Precisely: a singleton is cached in the deepest container that provides it or any of its transitive dependencies.
+
+Use cases: test mocks, request-scoped context, multi-tenancy, replacing part of a plugin.
+
+## Lifecycle Modes
+
+| mode                  | Where instances are cached                 | Disposed by              |
+| --------------------- | ------------------------------------------ | ------------------------ |
+| `singleton` (default) | The container chosen by the rule above     | The container caching it |
+| `scoped`              | The resolving container, one per container | That container           |
+| `transient`           | Not cached; a new instance per resolve     | The resolving container  |
+
+- A singleton that depends on a scoped provider, directly or transitively, throws `CAPTIVE_DEPENDENCY`.
+- Concurrent resolves of the same singleton run the factory only once.
+- Failed factories or initializations are not cached; the next resolve retries.
+
+## Async Initialization and Disposal
+
+```ts
+import { asyncDispose, dispose, init } from "@cyrenex/pondi";
+
+class Db {
+  #conn!: Connection;
+  constructor(readonly config: DbConfig) {}
+
+  async [init]() {
+    this.#conn = await connect(this.config.url);
+  }
+
+  async [asyncDispose]() {
+    await this.#conn.close();
+  }
+}
+```
+
+- **`init`**: after creating an instance, the container awaits `value[init]()` before handing it to dependents or caching it. Use it for async setup a constructor can't do. If `init` throws, the container disposes the instance and rethrows the original error.
+- **`asyncDispose` / `dispose`**: the standard `Symbol.asyncDispose` / `Symbol.dispose`, falling back to `Symbol.for(...)` on runtimes that lack them. They work with `await using` / `using`.
+- Both apply to objects returned by `ripple` factories and to instances created by `ripple.class`.
+
+Dispose a container with `await using` or `await app.dispose()`. Disposal order:
+
+1. Child containers first.
+2. Then instances owned by this container, in reverse creation order, so dependents are disposed before their dependencies.
+3. Multiple disposal errors are combined into one `AggregateError`.
+
+After disposal, `resolve`, `use`, and `fork` throw `DISPOSED`.
+
+## Errors
+
+All container errors are `PondError` instances with a `code` and a dependency `path`:
+
+| code                  | Thrown when                                                         |
+| --------------------- | ------------------------------------------------------------------- |
+| `MISSING_PROVIDER`    | No implementation exists for a key                                  |
+| `DUPLICATE_PROVIDER`  | A different implementation is registered for a key in one container |
+| `PROVIDER_LOCKED`     | Registering an implementation for a key that was already resolved   |
+| `CIRCULAR_DEPENDENCY` | Dependencies form a cycle                                           |
+| `CAPTIVE_DEPENDENCY`  | A singleton depends on a scoped provider, directly or transitively  |
+| `DISPOSED`            | The container has been disposed                                     |
+
+```ts
+try {
+  await app.resolve(Agent);
+} catch (error) {
+  if (error instanceof PondError && error.code === "MISSING_PROVIDER") {
+    console.error(error.path); // ["agent", "agent:config"]
+  }
+}
+```
+
+## Development
+
+```bash
+vp install # install dependencies
+vp test    # run tests
+vp check   # format, lint, and type check
+vp pack    # build
+vp run changeset # describe a change for the next release
+```
+
+## License
+
+[MIT](./LICENSE)
+
+## Special Thanks
+
+Thanks to all contributors for their contributions to pondi ❤️
+
+<a href="https://github.com/cyrenex/pondi/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=cyrenex/pondi" />
+</a>
+
+## Star History
+
+<a href="https://star-history.dera.page/#cyrenex/pondi&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date" />
+    <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date" />
+  </picture>
+</a>

package/README.zh-CN.md

@@ -0,0 +1,263 @@
+<h1 align="center">pondi</h1>
+
+<p align="center">投下一颗石子，泛起一圈涟漪。以字符串为 key 的 TypeScript 类型安全依赖注入库。</p>
+
+<p align="center">
+  [<a href="https://github.com/cyrenex/pondi/blob/master/README.md">English</a>] [<a href="https://www.npmjs.com/package/@cyrenex/pondi">npm</a>]
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@cyrenex/pondi"><img src="https://img.shields.io/npm/v/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669"></a>
+  <a href="https://www.npmjs.com/package/@cyrenex/pondi"><img src="https://img.shields.io/npm/dm/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669"></a>
+  <a href="https://bundlephobia.com/package/@cyrenex/pondi"><img src="https://img.shields.io/bundlephobia/minzip/@cyrenex/pondi?style=flat&colorA=080f12&colorB=1fa669&label=minzip"></a>
+  <a href="https://github.com/cyrenex/pondi/blob/master/LICENSE"><img src="https://img.shields.io/github/license/cyrenex/pondi.svg?style=flat&colorA=080f12&colorB=1fa669"></a>
+</p>
+
+> [!NOTE]
+> 不需要装饰器，不依赖 `reflect-metadata`，没有运行时依赖。只有 key、工厂和类型。
+
+TypeScript 里的大多数 DI 容器依赖装饰器和编译期生成的元数据，代价是额外的构建配置和只能写 class 的风格。pondi 反其道而行：**一个依赖就是一个带类型的字符串 key**。用 `pebble` 声明你需要什么，用 `ripple` 描述怎么构建它，再交给 `Pond` 把一切串起来。
+
+可以这样理解：往池塘里投一颗石子，石子（pebble）说明你需要什么，涟漪（ripple）是它最终变成的东西。
+
+## 特性
+
+- **全程类型推导**：工厂参数类型由依赖列表推导，顺序或结构写错会在编译期报错。
+- **彻底的异步支持**：异步工厂、异步 `init` 钩子，并发 resolve 同一个依赖时工厂只执行一次。
+- **分层池塘**：用 `fork()` 创建子容器，为测试、请求或租户覆盖实现；只有受影响的单例会被重建。
+- **确定的释放顺序**：支持 `await using`；先释放子容器，再按创建顺序的逆序释放实例。
+- **有用的错误信息**：每个 `PondError` 都带有 `code` 和完整的依赖路径 `path`。
+
+## 安装
+
+```bash
+pnpm add @cyrenex/pondi
+```
+
+## 快速开始
+
+```ts
+import { pebble, Pond, ripple } from "@cyrenex/pondi";
+
+interface AgentOptions {
+  url: string;
+}
+
+// 契约：只有类型，没有实现
+const AgentConfig = pebble<AgentOptions>("agent:config");
+
+// 插件：为契约提供实现
+const agentConfigPlugin = (options: AgentOptions) => ripple(AgentConfig, () => options);
+
+// 带默认实现的 token
+const Message = ripple("message", () => "Hello, Pond!");
+
+// 声明依赖，工厂参数的类型会自动推导
+const Agent = ripple("agent", [Message, AgentConfig], async (message, config) => {
+  const connection = await connect(config.url);
+  return {
+    send: () => connection.send(message),
+    async [Symbol.asyncDispose]() {
+      await connection.close();
+    },
+  };
+});
+
+await using app = new Pond().use(agentConfigPlugin({ url: "ws://localhost" }));
+const agent = await app.resolve(Agent); // { send: () => void }
+```
+
+## 核心概念
+
+| 概念        | 说明                                                          |
+| ----------- | ------------------------------------------------------------- |
+| `pebble<T>` | 契约：一个带类型的字符串 key，没有实现                        |
+| `ripple`    | 实现：key + 依赖 + 工厂 + 生命周期模式，同时也可以当 token 用 |
+| `Pond`      | 容器：注册实现、解析实例、管理生命周期                        |
+
+**key 就是身份。** `ripple("message", ...)`、`pebble("message")` 和字符串 `"message"` 指向同一个 token，`app.resolve(Message)` 与 `app.resolve("message")` 返回的是同一个实例。建议用命名空间来避免撞名，例如 `"agent:config"`。
+
+## 声明 ripple
+
+```ts
+ripple(key, factory, options?)
+ripple(key, deps, factory, options?)
+ripple(pebble, factory, options?)        // 为 pebble 提供实现，返回值类型必须符合契约
+ripple(pebble, deps, factory, options?)
+```
+
+- `deps` 里可以混写 pebble、ripple 和字符串，工厂按顺序收到解析好的值。
+- 工厂可以是 async 的。解析时会 `await` 工厂，依赖方拿到的永远是值，不是 Promise。
+- `options.mode` 默认是 `"singleton"`，见下文的[生命周期模式](#生命周期模式)。
+
+### ripple.class
+
+参数形式与 `ripple` 相同，只是把工厂换成 class，依赖会按顺序传给构造函数：
+
+```ts
+class Agent {
+  constructor(
+    readonly message: string,
+    readonly config: AgentOptions,
+  ) {}
+}
+
+const AgentRipple = ripple.class("agent", [Message, AgentConfig], Agent);
+const Logger = ripple.class(LoggerPebble, ConsoleLogger);
+```
+
+构造函数参数和依赖列表的类型会在编译期校验，依赖顺序写错会直接报错。
+
+## 解析与类型
+
+```ts
+await app.resolve(Agent); // 类型来自 ripple
+await app.resolve(AgentConfig); // 类型来自 pebble
+await app.resolve("message"); // 类型来自 Registry，未声明时为 unknown
+```
+
+想让纯字符串 key 也带类型，可以扩展 `Registry`。扩展后字符串 key 会有自动补全，`ripple` 的返回值也会按这里的声明做校验：
+
+```ts
+declare module "@cyrenex/pondi" {
+  interface Registry {
+    message: string;
+    "agent:config": AgentOptions;
+  }
+}
+```
+
+## 解析规则
+
+解析一个 token 时，按以下顺序查找实现：
+
+1. 当前容器及其所有父容器中通过 `use` 注册的实现，层级最近的优先。
+2. 如果 token 本身是一个 ripple，就使用它自带的默认实现。
+3. 都没有就抛出 `MISSING_PROVIDER`，错误里带有完整的依赖路径，例如 `agent -> agent:config`。
+
+所以 ripple 不需要事先 `use` 就能直接 resolve；pebble 和纯字符串则必须有某个容器提供实现。
+
+## 注册与覆盖
+
+### use
+
+```ts
+app.use(Message, agentConfigPlugin(opts), [PluginA, PluginB]); // 也接受数组，方便插件一次返回多个 ripple
+```
+
+- 同一个 ripple 对象重复 `use` 不会有任何效果。
+- 同一个 key 注册不同的实现，会抛出 `DUPLICATE_PROVIDER`。
+- 一个 key 被 resolve 过之后，就不能在当前容器及其祖先容器中再注册，否则抛出 `PROVIDER_LOCKED`。这是为了避免新旧实例同时存在。
+
+### fork
+
+覆盖实现只有一种方式：创建子容器，在子容器里注册同名 key。
+
+```ts
+await using test = app.fork().use(ripple("message", () => "mock"));
+
+await test.resolve(Agent); // 使用 mock 版本的 message
+await app.resolve(Agent); // 父容器不受影响
+```
+
+子容器中，**依赖被覆盖到的 singleton 会重新创建**，没被影响的 singleton 仍然和父容器共享同一个实例。具体来说，一个 singleton 会缓存在"它自身的实现以及所有传递依赖的实现"当中注册位置最深的那个容器里。
+
+适用场景：测试 mock、请求级上下文、多租户、替换插件中的部分实现。
+
+## 生命周期模式
+
+| mode                | 实例缓存位置                 | 由谁释放       |
+| ------------------- | ---------------------------- | -------------- |
+| `singleton`（默认） | 按上面的规则自动确定的容器   | 缓存它的容器   |
+| `scoped`            | 发起解析的容器，每个容器一份 | 该容器         |
+| `transient`         | 不缓存，每次解析都新建       | 发起解析的容器 |
+
+- singleton 直接或间接依赖 scoped 时会抛出 `CAPTIVE_DEPENDENCY`。
+- 同一个 singleton 被并发解析时，工厂只会执行一次。
+- 工厂或初始化失败的结果不会被缓存，下次解析会重试。
+
+## 异步初始化与资源释放
+
+```ts
+import { asyncDispose, dispose, init } from "@cyrenex/pondi";
+
+class Db {
+  #conn!: Connection;
+  constructor(readonly config: DbConfig) {}
+
+  async [init]() {
+    this.#conn = await connect(this.config.url);
+  }
+
+  async [asyncDispose]() {
+    await this.#conn.close();
+  }
+}
+```
+
+- **`init`**：实例创建后，容器会先 `await value[init]()`，完成后才把实例交给依赖方、写入缓存。它用来做构造函数里做不了的异步初始化。如果 `init` 抛错，容器会先释放这个实例，再抛出原错误。
+- **`asyncDispose` / `dispose`**：就是标准的 `Symbol.asyncDispose` / `Symbol.dispose`。运行时不支持时会退回 `Symbol.for(...)`，可以直接配合 `await using` / `using` 使用。
+- 以上机制对 `ripple` 工厂返回的对象和 `ripple.class` 创建的实例都有效。
+
+释放容器时可以用 `await using`，也可以调用 `await app.dispose()`。释放顺序是：
+
+1. 先释放所有子容器；
+2. 再按创建顺序的逆序，释放当前容器持有的实例，也就是先释放依赖方，再释放被依赖的实例；
+3. 多个释放错误会合并成一个 `AggregateError` 抛出。
+
+容器释放后，再调用 `resolve`、`use` 或 `fork` 都会抛出 `DISPOSED`。
+
+## 错误
+
+所有容器错误都是 `PondError`，带有 `code` 和依赖路径 `path`：
+
+| code                  | 触发条件                                  |
+| --------------------- | ----------------------------------------- |
+| `MISSING_PROVIDER`    | 找不到 key 的实现                         |
+| `DUPLICATE_PROVIDER`  | 同一个容器里，同一个 key 注册了不同的实现 |
+| `PROVIDER_LOCKED`     | key 已经被 resolve 过，又试图注册新的实现 |
+| `CIRCULAR_DEPENDENCY` | 存在循环依赖                              |
+| `CAPTIVE_DEPENDENCY`  | singleton 直接或间接依赖了 scoped         |
+| `DISPOSED`            | 容器已释放                                |
+
+```ts
+try {
+  await app.resolve(Agent);
+} catch (error) {
+  if (error instanceof PondError && error.code === "MISSING_PROVIDER") {
+    console.error(error.path); // ["agent", "agent:config"]
+  }
+}
+```
+
+## 开发
+
+```bash
+vp install # 安装依赖
+vp test    # 运行测试
+vp check   # 格式、lint、类型检查
+vp pack    # 构建
+vp run changeset # 为下一次发布记录变更
+```
+
+## License
+
+[MIT](./LICENSE)
+
+## 特别感谢
+
+感谢所有为 pondi 做出贡献的人 ❤️
+
+<a href="https://github.com/cyrenex/pondi/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=cyrenex/pondi" />
+</a>
+
+## Star 历史
+
+<a href="https://star-history.dera.page/#cyrenex/pondi&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date" />
+    <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=cyrenex/pondi&type=Date" />
+  </picture>
+</a>

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+/**
+ * The standard `Symbol.asyncDispose`, falling back to `Symbol.for("Symbol.asyncDispose")`
+ * on runtimes that lack it. Works with `await using`.
+ */
+export declare const asyncDispose: typeof Symbol.asyncDispose;
+/**
+ * The standard `Symbol.dispose`, falling back to `Symbol.for("Symbol.dispose")`
+ * on runtimes that lack it. Works with `using`.
+ */
+export declare const dispose: typeof Symbol.dispose;
+/**
+ * Lifecycle hook awaited by the container after an instance is created and before it is
+ * handed to dependents. Use it for async initialization a constructor cannot do.
+ * If it throws, the instance is disposed and the error propagates.
+ */
+export declare const init: unique symbol;
+interface Initializable {
+  [init](): void | PromiseLike<void>;
+}
+declare const TYPE: unique symbol;
+declare const RIPPLE: unique symbol;
+/**
+ * Type registry for string keys. Augment it to get types for plain string tokens:
+ *
+ * ```ts
+ * declare module "@cyrenex/pondi" {
+ *   interface Registry { message: string }
+ * }
+ * ```
+ */
+interface Registry {}
+type Mode = "singleton" | "scoped" | "transient";
+interface RippleOptions {
+  /** @default "singleton" */
+  mode?: Mode;
+}
+/** A typed contract identified by its string key. Has no implementation. */
+interface Pebble<T> {
+  readonly key: string;
+  /** Phantom field carrying the value type; absent at runtime. */
+  readonly [TYPE]: T;
+}
+/** A pebble with an implementation. */
+interface Ripple<T> extends Pebble<T> {
+  readonly deps: readonly Token[];
+  readonly factory: (...args: any[]) => T | PromiseLike<T>;
+  readonly mode: Mode;
+  readonly [RIPPLE]: true;
+}
+type Token = Pebble<any> | string;
+/** String keys with autocomplete for registered ones, while still accepting any string. */
+type TokenInput = Pebble<any> | (keyof Registry & string) | (string & {});
+type KeyValue<K extends string> = K extends keyof Registry ? Registry[K] : unknown;
+type Value<K> = K extends Pebble<infer T> ? T : K extends string ? KeyValue<K> : never;
+type Values<D extends readonly Token[]> = { -readonly [I in keyof D]: Value<D[I]>; };
+type Factory<D extends readonly Token[], T> = (...args: Values<D>) => T | PromiseLike<T>;
+export declare function pebble<T>(key: string): Pebble<T>;
+export declare function ripple<T>(pebble: Pebble<T>, factory: Factory<[], T>, options?: RippleOptions): Ripple<T>;
+export declare namespace ripple {
+  export { rippleClass as class };
+}
+export declare function ripple<T, const D extends readonly Token[]>(pebble: Pebble<T>, deps: D, factory: Factory<D, T>, options?: RippleOptions): Ripple<T>;
+export declare function ripple<K extends string, T extends KeyValue<K>>(key: K, factory: Factory<[], T>, options?: RippleOptions): Ripple<T>;
+export declare function ripple<K extends string, const D extends readonly Token[], T extends KeyValue<K>>(key: K, deps: D, factory: Factory<D, T>, options?: RippleOptions): Ripple<T>;
+type Constructor<D extends readonly Token[], T> = new (...args: Values<D>) => T;
+declare function rippleClass<T>(pebble: Pebble<T>, cls: Constructor<[], T>, options?: RippleOptions): Ripple<T>;
+declare function rippleClass<T, const D extends readonly Token[]>(pebble: Pebble<T>, deps: D, cls: Constructor<D, T>, options?: RippleOptions): Ripple<T>;
+declare function rippleClass<K extends string, T extends KeyValue<K>>(key: K, cls: Constructor<[], T>, options?: RippleOptions): Ripple<T>;
+declare function rippleClass<K extends string, const D extends readonly Token[], T extends KeyValue<K>>(key: K, deps: D, cls: Constructor<D, T>, options?: RippleOptions): Ripple<T>;
+export declare class Pond implements AsyncDisposable {
+  #private;
+  /**
+   * Register providers in this container. Accepts ripples or arrays of ripples (e.g. from plugins).
+   * Registering the same ripple twice is a no-op; a different ripple for an existing key throws.
+   * Use `fork()` to shadow a provider from a parent container.
+   */
+  use(...items: (Ripple<any> | readonly Ripple<any>[])[]): this;
+  /** Create a child container. Its `use()` may shadow providers of this container. */
+  fork(): Pond;
+  resolve<K extends TokenInput>(token: K): Promise<Value<K>>;
+  /** Dispose child containers, then owned instances in reverse creation order. */
+  [asyncDispose](): Promise<void>;
+  dispose(): Promise<void>;
+}
+type PondErrorCode = "DUPLICATE_PROVIDER" | "PROVIDER_LOCKED" | "MISSING_PROVIDER" | "CIRCULAR_DEPENDENCY" | "CAPTIVE_DEPENDENCY" | "DISPOSED";
+export declare class PondError extends Error {
+  name: string;
+  readonly code: PondErrorCode;
+  /** Dependency path leading to the error, outermost first. */
+  readonly path: readonly string[];
+  constructor(code: PondErrorCode, message: string, path?: readonly string[]);
+}
+export type { Constructor, Factory, Initializable, Mode, Pebble, PondErrorCode, Registry, Ripple, RippleOptions, Token, TokenInput, Value, Values };

package/dist/index.mjs

@@ -0,0 +1,264 @@
+// src/errors.ts
+var PondError = class extends Error {
+	name = "PondError";
+	code;
+	/** Dependency path leading to the error, outermost first. */
+	path;
+	constructor(code, message, path = []) {
+		super(path.length > 0 ? `${message} (${path.join(" -> ")})` : message);
+		this.code = code;
+		this.path = path;
+	}
+};
+// src/lifecycle.ts
+/**
+* The standard `Symbol.asyncDispose`, falling back to `Symbol.for("Symbol.asyncDispose")`
+* on runtimes that lack it. Works with `await using`.
+*/
+const asyncDispose = Symbol.asyncDispose ?? Symbol.for("Symbol.asyncDispose");
+/**
+* The standard `Symbol.dispose`, falling back to `Symbol.for("Symbol.dispose")`
+* on runtimes that lack it. Works with `using`.
+*/
+const dispose = Symbol.dispose ?? Symbol.for("Symbol.dispose");
+/**
+* Lifecycle hook awaited by the container after an instance is created and before it is
+* handed to dependents. Use it for async initialization a constructor cannot do.
+* If it throws, the instance is disposed and the error propagates.
+*/
+const init = Symbol.for("@cyrenex/pondi.init");
+function isObject(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+function isDisposable(value) {
+	return isObject(value) && (asyncDispose in value || dispose in value);
+}
+async function disposeValue(value) {
+	if (!isDisposable(value)) return;
+	if (asyncDispose in value) await value[asyncDispose]();
+	else value[dispose]();
+}
+async function initValue(value) {
+	if (!isObject(value) || typeof value[init] !== "function") return;
+	try {
+		await value[init]();
+	} catch (error) {
+		try {
+			await disposeValue(value);
+		} catch (disposeError) {
+			throw new AggregateError([error, disposeError], "Initialization and cleanup both failed");
+		}
+		throw error;
+	}
+}
+// src/token.ts
+const RIPPLE = Symbol("pondi.ripple");
+function pebble(key) {
+	return Object.freeze({ key });
+}
+function ripple(target, depsOrFactory, factoryOrOptions, maybeOptions) {
+	const key = keyOf(target);
+	let deps;
+	let factory;
+	let options;
+	if (typeof depsOrFactory === "function") {
+		deps = [];
+		factory = depsOrFactory;
+		options = factoryOrOptions;
+	} else {
+		deps = depsOrFactory;
+		factory = factoryOrOptions;
+		options = maybeOptions;
+	}
+	if (typeof factory !== "function") throw new TypeError(`ripple("${key}"): factory must be a function`);
+	const mode = options?.mode ?? "singleton";
+	if (mode !== "singleton" && mode !== "scoped" && mode !== "transient") throw new TypeError(`ripple("${key}"): unknown mode "${String(mode)}"`);
+	return Object.freeze({
+		key,
+		deps: Object.freeze([...deps]),
+		factory,
+		mode,
+		[RIPPLE]: true
+	});
+}
+function rippleClass(target, depsOrClass, classOrOptions, maybeOptions) {
+	const [deps, cls, options] = Array.isArray(depsOrClass) ? [
+		depsOrClass,
+		classOrOptions,
+		maybeOptions
+	] : [
+		[],
+		depsOrClass,
+		classOrOptions
+	];
+	if (typeof cls !== "function") throw new TypeError(`ripple.class("${keyOf(target)}"): expected a class`);
+	return ripple(target, deps, (...args) => new cls(...args), options);
+}
+/** Like `ripple`, but instantiates a class with the resolved dependencies as constructor arguments. */
+ripple.class = rippleClass;
+function isRipple(value) {
+	return typeof value === "object" && value !== null && RIPPLE in value;
+}
+function keyOf(token) {
+	return typeof token === "string" ? token : token.key;
+}
+// src/container.ts
+var Pond = class Pond {
+	#parent;
+	/** Containers from root to this one. */
+	#chain = [this];
+	#children = /* @__PURE__ */ new Set();
+	#registry = /* @__PURE__ */ new Map();
+	/** Keys whose provider resolution is fixed because something resolved them through this container. */
+	#locked = /* @__PURE__ */ new Set();
+	#analysis = /* @__PURE__ */ new Map();
+	#cache = /* @__PURE__ */ new Map();
+	/** Created instances in creation order, disposed in reverse. */
+	#instances = [];
+	#disposing;
+	get #depth() {
+		return this.#chain.length - 1;
+	}
+	/**
+	* Register providers in this container. Accepts ripples or arrays of ripples (e.g. from plugins).
+	* Registering the same ripple twice is a no-op; a different ripple for an existing key throws.
+	* Use `fork()` to shadow a provider from a parent container.
+	*/
+	use(...items) {
+		this.#assertAlive();
+		for (const item of items.flat()) {
+			if (!isRipple(item)) throw new TypeError("Pond.use() expects ripples");
+			this.#register(item);
+		}
+		return this;
+	}
+	/** Create a child container. Its `use()` may shadow providers of this container. */
+	fork() {
+		this.#assertAlive();
+		const child = new Pond();
+		child.#parent = this;
+		child.#chain = [...this.#chain, child];
+		this.#children.add(child);
+		return child;
+	}
+	resolve(token) {
+		try {
+			return this.#resolve(token);
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	/** Dispose child containers, then owned instances in reverse creation order. */
+	[asyncDispose]() {
+		this.#disposing ??= this.#dispose();
+		return this.#disposing;
+	}
+	dispose() {
+		return this[asyncDispose]();
+	}
+	#register(provider) {
+		const existing = this.#registry.get(provider.key);
+		if (existing === provider) return;
+		if (this.#locked.has(provider.key)) throw new PondError("PROVIDER_LOCKED", `"${provider.key}" has already been resolved through this container and can no longer be provided here`);
+		if (existing) throw new PondError("DUPLICATE_PROVIDER", `A different provider for "${provider.key}" is already registered in this container; use fork() to shadow it`);
+		this.#registry.set(provider.key, provider);
+	}
+	#lookup(token, path) {
+		const key = keyOf(token);
+		for (let depth = this.#depth; depth >= 0; depth--) {
+			const provider = this.#chain[depth].#registry.get(key);
+			if (provider) return {
+				provider,
+				depth
+			};
+		}
+		if (isRipple(token)) {
+			this.#chain[0].#registry.set(key, token);
+			return {
+				provider: token,
+				depth: 0
+			};
+		}
+		throw new PondError("MISSING_PROVIDER", `No provider for "${key}"`, [...path, key]);
+	}
+	/** Statically walk the dependency graph to find providers, cycles, and singleton homes. */
+	#analyze(token, path) {
+		const key = keyOf(token);
+		const memo = this.#analysis.get(key);
+		if (memo) return memo;
+		if (path.includes(key)) throw new PondError("CIRCULAR_DEPENDENCY", `Circular dependency on "${key}"`, [...path, key]);
+		const { provider, depth } = this.#lookup(token, path);
+		path.push(key);
+		const deps = provider.deps.map((dep) => this.#analyze(dep, path));
+		path.pop();
+		let info;
+		const mode = provider.mode;
+		if (mode === "scoped") info = {
+			provider,
+			home: this.#depth,
+			scoped: true
+		};
+		else {
+			const scopedDep = deps.find((d) => d.scoped);
+			if (mode === "singleton" && scopedDep) throw new PondError("CAPTIVE_DEPENDENCY", `Singleton "${key}" cannot depend on scoped "${scopedDep.provider.key}"`, [...path, key]);
+			info = {
+				provider,
+				home: Math.max(depth, ...deps.map((d) => d.home)),
+				scoped: scopedDep !== void 0
+			};
+		}
+		for (const c of this.#chain) c.#locked.add(key);
+		this.#analysis.set(key, info);
+		return info;
+	}
+	#resolve(token) {
+		this.#assertAlive();
+		const { provider, home } = this.#analyze(token, []);
+		if (provider.mode === "transient") return this.#instantiate(provider);
+		const target = provider.mode === "singleton" ? this.#chain[home] : this;
+		if (target !== this) return target.#resolve(token);
+		const cached = this.#cache.get(provider.key);
+		if (cached) return cached;
+		const pending = this.#instantiate(provider);
+		this.#cache.set(provider.key, pending);
+		pending.catch(() => {
+			if (this.#cache.get(provider.key) === pending) this.#cache.delete(provider.key);
+		});
+		return pending;
+	}
+	async #instantiate(provider) {
+		const args = await Promise.all(provider.deps.map((dep) => this.#resolve(dep)));
+		const value = await provider.factory(...args);
+		await initValue(value);
+		if (this.#disposing) {
+			await disposeValue(value);
+			throw new PondError("DISPOSED", `Container was disposed while creating "${provider.key}"`);
+		}
+		if (isDisposable(value)) this.#instances.push(value);
+		return value;
+	}
+	async #dispose() {
+		const errors = [];
+		for (const child of [...this.#children].reverse()) try {
+			await child.dispose();
+		} catch (error) {
+			errors.push(error);
+		}
+		await Promise.allSettled(this.#cache.values());
+		for (const value of this.#instances.reverse()) try {
+			await disposeValue(value);
+		} catch (error) {
+			errors.push(error);
+		}
+		this.#instances.length = 0;
+		this.#cache.clear();
+		this.#analysis.clear();
+		if (this.#parent) this.#parent.#children.delete(this);
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose Pond container");
+	}
+	#assertAlive() {
+		if (this.#disposing) throw new PondError("DISPOSED", "Container has been disposed");
+	}
+};
+export { Pond, PondError, asyncDispose, dispose, init, pebble, ripple };

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@cyrenex/pondi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Type-safe, string-keyed dependency injection with async factories and scoped disposal.",
+  "homepage": "https://github.com/cyrenex/pondi#readme",
+  "bugs": {
+    "url": "https://github.com/cyrenex/pondi/issues"
+  },
+  "license": "MIT",
+  "author": "byc <bycrxemail@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyrenex/pondi.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.3",
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vite-plus": "1.4.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.16.1",
+      "onFail": "download"
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "changeset": "changeset",
+    "release": "changeset publish"
+  }
 }