better-effect 0.1.0

package/README.md

@@ -0,0 +1,336 @@
+# better-effect
+
+Lightweight Effect-inspired primitives built around [`better-result`](https://www.npmjs.com/package/better-result).
+
+`better-effect` focuses on a small set of ideas that are useful in application code without bringing in a full effect runtime:
+
+- **Service** — contextual dependency access with `yield*`
+- **Layer** — declarative composition of live/test environments
+- **Resource** — safe acquire/use/release lifecycle
+- **DI adapters** — dependency resolution is delegated to an external container instead of being reimplemented by the library
+
+The goal is not to recreate Effect. The goal is to provide a small, composable layer on top of `better-result`.
+
+## Installation
+
+```bash
+bun add better-effect better-result
+```
+
+If you want the ITI adapter:
+
+```bash
+bun add iti
+```
+
+## Service
+
+A service is a class that also acts as its own dependency token.
+
+```ts
+import { Result } from 'better-result'
+import { Service } from 'better-effect'
+
+export class Database extends Service<Database>() {
+  findUser(email: string) {
+    return Promise.resolve({
+      id: '1',
+      email
+    })
+  }
+}
+
+export class UserRepository extends Service<UserRepository>() {
+  findByEmail(email: string) {
+    return Result.gen(async function* () {
+      const database = yield* Database
+
+      const user = await database.findUser(email)
+
+      return Result.ok(user)
+    })
+  }
+}
+```
+
+There are no string tokens:
+
+```ts
+const database = yield * Database
+```
+
+The class itself is the identity used by the resolver, and the result is inferred as `Database`.
+
+### Why classes are tokens
+
+Using constructors directly avoids duplicated identifiers such as:
+
+```ts
+Service<AuthService>()('authService')
+```
+
+and prevents string-key collisions or typos.
+
+Conceptually:
+
+```text
+yield* AuthService
+        │
+        ▼
+ServiceRuntime
+        │
+        ▼
+ServiceResolver
+        │
+        ▼
+AuthService instance
+```
+
+## Layer
+
+A Layer describes which implementations form an application environment.
+
+It does **not** implement dependency resolution. That remains the responsibility of the configured backend.
+
+```ts
+import { Layer } from 'better-effect'
+
+export const DatabaseLive = Layer.scoped(
+  Database,
+  async () => {
+    const database = new Database()
+
+    await database.connect()
+
+    return database
+  },
+  (database) => database.close()
+)
+
+export const UserRepositoryLive = Layer.make(UserRepository, () => new UserRepository())
+
+export const AppLive = Layer.merge(DatabaseLive, UserRepositoryLive)
+```
+
+The core Layer API intentionally stays small:
+
+```ts
+Layer.make(Service, acquire)
+Layer.succeed(Service, instance)
+Layer.scoped(Service, acquire, release)
+Layer.merge(...layers)
+Layer.override(base, ...overrides)
+```
+
+### Test environments
+
+Layers make implementation replacement explicit:
+
+```ts
+const DatabaseTest = Layer.succeed(Database, new InMemoryDatabase())
+
+const AppTest = Layer.override(AppLive, DatabaseTest)
+```
+
+## ITI adapter
+
+`better-effect` does not depend on ITI in its core. ITI is just one possible backend.
+
+```ts
+import { buildLayer } from 'better-effect'
+
+import { ItiLayerBackend } from 'better-effect/iti'
+
+const runtime = await buildLayer(AppLive, new ItiLayerBackend())
+
+try {
+  await main()
+} finally {
+  await runtime.dispose()
+}
+```
+
+This keeps application code independent from the DI container.
+
+A different backend can implement the same resolver/backend contracts without changing Services or Layers.
+
+## Resource
+
+`Resource.acquireUseRelease()` handles local resource lifecycle while preserving typed `Result` errors.
+
+```ts
+import { Resource } from 'better-effect'
+
+const result = await Resource.acquireUseRelease({
+  name: 'transaction',
+
+  acquire: () => database.begin(),
+
+  use: (transaction) => executeCommand(transaction),
+
+  release: (transaction) => transaction.close()
+})
+```
+
+When `release` is omitted, `Resource` attempts to use the JavaScript explicit resource management protocol:
+
+```ts
+Symbol.asyncDispose
+Symbol.dispose
+```
+
+### Error precedence
+
+If both `use` and `release` fail, the error produced by `use` is preserved.
+
+The precedence is:
+
+```text
+1. use failure
+2. release failure
+3. successful use value
+```
+
+Acquisition exceptions, rejected promises, and unexpected failures are normalized through `better-result`.
+
+## Service vs Layer vs Resource
+
+| Primitive       | Responsibility                                        |
+| --------------- | ----------------------------------------------------- |
+| `Service`       | Request a contextual dependency                       |
+| `Layer`         | Describe the implementations that form an environment |
+| `Resource`      | Manage a resource local to one operation              |
+| DI backend      | Resolve, cache and dispose service instances          |
+| `better-result` | Typed failures and generator control flow             |
+
+## Complete example
+
+The repository contains a TODO API example under:
+
+```text
+examples/todo-api
+```
+
+It demonstrates:
+
+- Bun HTTP server
+- SQLite in memory with `Bun.SQL`
+- user login
+- session authentication
+- TODO CRUD
+- `Service` dependency access
+- Layer composition
+- scoped database lifecycle
+- `Resource.acquireUseRelease()`
+- ITI as the DI backend
+
+Run it from the repository root:
+
+```bash
+bun examples/todo-api/index.ts
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run tests:
+
+```bash
+bun test
+```
+
+Typecheck:
+
+```bash
+bun run typecheck
+```
+
+Run the full quality gate:
+
+```bash
+bun run check
+```
+
+The project uses:
+
+- Bun as package manager and test runner
+- TypeScript
+- tsdown for library builds
+- Oxlint
+- Oxfmt
+- publint
+
+## Design principles
+
+### Keep the core small
+
+`better-effect` should not grow into a second Effect runtime.
+
+The core intentionally does not implement:
+
+- fibers
+- schedules
+- streams
+- queues
+- a dependency graph runtime
+- a custom DI container
+- a custom Context
+- a custom Scope runtime
+- `Effect<A, E, R>`
+
+### Delegate instead of rebuilding
+
+Dependency resolution, caching and container lifecycle belong to DI backends.
+
+`better-effect` supplies the protocol and composition primitives.
+
+### Preserve inference at public boundaries
+
+Type safety is part of the API.
+
+For example:
+
+```ts
+const auth = yield * AuthService
+// AuthService
+```
+
+and:
+
+```ts
+const database = await ServiceRuntime.resolve(Database)
+// Database
+```
+
+must preserve exact instance types.
+
+### Type erasure stays internal
+
+Layers may store heterogeneous providers internally using erased types.
+
+The public constructors (`Layer.make`, `Layer.succeed`, `Layer.scoped`) are responsible for preserving the relationship between a Service token and its instance type.
+
+## Current scope
+
+The project is intentionally small and experimental.
+
+The initial scope is:
+
+```text
+Service
+Layer
+Resource
+DI adapters
+better-result integration
+```
+
+New abstractions should only be added when they solve a concrete problem without duplicating responsibilities already handled well by another library.
+
+## License
+
+MIT

package/dist/adapters/iti.d.mts

@@ -0,0 +1,2 @@
+import { t as ItiLayerBackend } from "../iti-xXAb9-Qs.mjs";
+export { ItiLayerBackend };

package/dist/adapters/iti.mjs

@@ -0,0 +1,30 @@
+import { createContainer } from "iti";
+//#region src/adapters/iti.ts
+var ItiLayerBackend = class {
+	container = createContainer();
+	keys = /* @__PURE__ */ new WeakMap();
+	nextId = 0;
+	keyFor(token) {
+		const existing = this.keys.get(token);
+		if (existing) return existing;
+		const key = `better-effect:${token.name || "Service"}:${this.nextId++}`;
+		this.keys.set(token, key);
+		return key;
+	}
+	register(provider) {
+		const key = this.keyFor(provider.service);
+		this.container = this.container.add({ [key]: provider.acquire });
+		if (provider.release) this.container = this.container.addDisposer({ [key]: provider.release });
+	}
+	resolve(token) {
+		const key = this.keyFor(token);
+		return this.container.get(key);
+	}
+	async disposeAll() {
+		await this.container.disposeAll();
+	}
+};
+//#endregion
+export { ItiLayerBackend };
+
+//# sourceMappingURL=iti.mjs.map

package/dist/adapters/iti.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport type { LayerBackend } from '../layer'\n\nimport type { AnyServiceToken, ServiceToken } from '../service'\nimport type { LayerProvider } from '../layer/types'\n\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new WeakMap<ServiceToken<any>, string>()\n\n  private nextId = 0\n\n  private keyFor(token: AnyServiceToken): string {\n    const existing = this.keys.get(token)\n\n    if (existing) {\n      return existing\n    }\n\n    const name = (token as Function).name || 'Service'\n\n    const key = `better-effect:${name}:${this.nextId++}`\n\n    this.keys.set(token, key)\n\n    return key\n  }\n\n  register(provider: LayerProvider): void {\n    const key = this.keyFor(provider.service)\n\n    this.container = this.container.add({\n      [key]: provider.acquire\n    })\n\n    if (provider.release) {\n      this.container = this.container.addDisposer({\n        [key]: provider.release\n      })\n    }\n  }\n\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    const key = this.keyFor(token)\n\n    return this.container.get(key) as InstanceType<T> | PromiseLike<InstanceType<T>>\n  }\n\n  async disposeAll(): Promise<void> {\n    await this.container.disposeAll()\n  }\n}\n"],"mappings":";;AAOA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,QAAmC;CAE/D,SAAiB;CAEjB,OAAe,OAAgC;EAC7C,MAAM,WAAW,KAAK,KAAK,IAAI,KAAK;EAEpC,IAAI,UACF,OAAO;EAKT,MAAM,MAAM,iBAFE,MAAmB,QAAQ,UAEP,GAAG,KAAK;EAE1C,KAAK,KAAK,IAAI,OAAO,GAAG;EAExB,OAAO;CACT;CAEA,SAAS,UAA+B;EACtC,MAAM,MAAM,KAAK,OAAO,SAAS,OAAO;EAExC,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,SAAS,QAClB,CAAC;EAED,IAAI,SAAS,SACX,KAAK,YAAY,KAAK,UAAU,YAAY,GACzC,MAAM,SAAS,QAClB,CAAC;CAEL;CAEA,QAAmC,OAA0D;EAC3F,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,OAAO,KAAK,UAAU,IAAI,GAAG;CAC/B;CAEA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;AACF"}

package/dist/index.d.mts

@@ -0,0 +1,79 @@
+import { a as LayerProvider, c as ServiceClass, i as ServiceRuntime, l as ServiceInstance, n as LayerBackend, o as MaybePromise$1, r as ServiceResolver, s as AnyServiceToken, t as ItiLayerBackend } from "./iti-xXAb9-Qs.mjs";
+import { Result, UnhandledException } from "better-result";
+//#region src/layer/layer.d.ts
+declare class Layer {
+  readonly providers: readonly LayerProvider[];
+  private constructor();
+  static make<S extends ServiceClass<any>>(service: S, acquire: () => MaybePromise$1<InstanceType<S>>): Layer;
+  static succeed<S extends ServiceClass<any>>(service: S, instance: InstanceType<S>): Layer;
+  static scoped<S extends ServiceClass<any>>(service: S, acquire: () => MaybePromise$1<InstanceType<S>>, release: (instance: InstanceType<S>) => MaybePromise$1<void>): Layer;
+  static merge(...layers: readonly Layer[]): Layer;
+  static override(base: Layer, ...overrides: readonly Layer[]): Layer;
+}
+//#endregion
+//#region src/layer/runtime.d.ts
+interface BuiltLayer {
+  dispose(): Promise<void>;
+}
+declare const buildLayer: (layer: Layer, backend: LayerBackend) => Promise<BuiltLayer>;
+declare class RuntimeLayer {
+  static build: typeof buildLayer;
+}
+//#endregion
+//#region src/service/service.d.ts
+declare function Service<Self>(): {
+  new (): {};
+  [Symbol.asyncIterator](): AsyncGenerator<never, Self, unknown>;
+};
+//#endregion
+//#region src/resource/errors.d.ts
+declare const ResourceReleaseFailure_base: import("better-result").TaggedErrorClass<"ResourceReleaseFailure">;
+declare class ResourceReleaseFailure extends ResourceReleaseFailure_base<{
+  readonly resource: string;
+  readonly cause: unknown;
+  readonly message: string;
+}> {}
+//#endregion
+//#region src/resource/types.d.ts
+type MaybePromise<T> = T | PromiseLike<T>;
+type AsyncResult<T, E> = MaybePromise<Result<T, E>>;
+type ReleaseOutcome = void | Result<void, unknown>;
+type DisposableResource = {
+  [Symbol.dispose]?: () => void;
+  [Symbol.asyncDispose]?: () => MaybePromise<void>;
+};
+type AcquireUseReleaseOptions<R, A, AcquireError, UseError> = {
+  /**
+   * Nome utilizado para identificar o recurso
+   * em eventuais erros de release.
+   */
+  readonly name: string;
+  /**
+   * Adquire o recurso.
+   */
+  readonly acquire: () => AsyncResult<R, AcquireError>;
+  /**
+   * Executa a operação usando o recurso.
+   */
+  readonly use: (resource: R) => AsyncResult<A, UseError>;
+  /**
+   * Libera o recurso.
+   *
+   * Se não informado, Resource tentará usar:
+   *
+   * Symbol.asyncDispose
+   * Symbol.dispose
+   *
+   * nessa ordem.
+   */
+  readonly release?: (resource: R) => MaybePromise<ReleaseOutcome>;
+};
+//#endregion
+//#region src/resource/resource.d.ts
+declare const acquireUseRelease: <R, A, AcquireError, UseError>({ name, acquire, use, release }: AcquireUseReleaseOptions<R, A, AcquireError, UseError>) => Promise<Result<A, AcquireError | UseError | UnhandledException | ResourceReleaseFailure>>;
+declare const Resource: {
+  readonly acquireUseRelease: typeof acquireUseRelease;
+};
+//#endregion
+export { type AcquireUseReleaseOptions, type AnyServiceToken, type AsyncResult, type BuiltLayer, type DisposableResource, ItiLayerBackend, Layer, type LayerBackend, type MaybePromise, type ReleaseOutcome, Resource, ResourceReleaseFailure, RuntimeLayer, Service, type ServiceInstance, type ServiceResolver, ServiceRuntime, buildLayer };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/layer/layer.ts","../src/layer/runtime.ts","../src/service/service.ts","../src/resource/errors.ts","../src/resource/types.ts","../src/resource/resource.ts"],"mappings":";;;cAIa;WACkB,oBAAoB;UAA1C;SAEA,KAAK,UAAU,mBACpB,SAAS,GACT,eAAe,eAAa,aAAa,MACxC;SASI,QAAQ,UAAU,mBAAmB,SAAS,GAAG,UAAU,aAAa,KAAK;SAI7E,OAAO,UAAU,mBACtB,SAAS,GACT,eAAe,eAAa,aAAa,KACzC,UAAU,UAAU,aAAa,OAAO,uBACvC;SAWI,SAAS,iBAAiB,UAAU;SAkBpC,SAAS,MAAM,UAAU,oBAAoB,UAAU;;;;UCnD/C;EACf,WAAW;;cAGA,aAAU,OAAiB,OAAK,SAAW,iBAAe,QAAQ;cAkBlE;SACJ,cAAK;;;;iBCxBE,QAAQ;;GAGoB,OAAA,kBAAA,sBAAsB;;;;;cCLrD,+BAA+B;WACjC;WACA;WACA;;;;KCHC,aAAa,KAAK,IAAI,YAAY;KAElC,YAAY,GAAG,KAAK,aAAa,OAAW,GAAG;KAE/C,wBAAwB;KAExB;GACT,OAAO;GAEP,OAAO,sBAAsB;;KAGpB,yBAAyB,GAAG,GAAG,cAAc;;;;;WAK9C;;;;WAKA,eAAe,YAAY,GAAG;;;;WAK9B,MAAM,UAAU,MAAM,YAAY,GAAG;;;;;;;;;;;WAYrC,WAAW,UAAU,MAAM,aAAa;;;;cCjC7C,oBAAqB,GAAG,GAAG,cAAc,YAAQ,MAAA,SAAA,KAAA,WAKpD,yBAAyB,GAAG,GAAG,cAAc,cAAY,QAC1D,OAAW,GAAG,eAAe,WAAW,qBAAqB;cAmBlD;qCAAA"}

package/dist/index.mjs

@@ -0,0 +1,139 @@
+import { ItiLayerBackend } from "./adapters/iti.mjs";
+import { Result, TaggedError } from "better-result";
+//#region src/service/runtime.ts
+let currentResolver;
+var ServiceRuntime = class {
+	static configure(resolver) {
+		currentResolver = resolver;
+	}
+	static async resolve(token) {
+		if (!currentResolver) throw new Error("ServiceRuntime has not been configured");
+		return await currentResolver.resolve(token);
+	}
+	static reset() {
+		currentResolver = void 0;
+	}
+};
+//#endregion
+//#region src/service/service.ts
+function Service() {
+	return class {
+		static async *[Symbol.asyncIterator]() {
+			return await ServiceRuntime.resolve(this);
+		}
+	};
+}
+//#endregion
+//#region src/layer/layer.ts
+var Layer = class Layer {
+	providers;
+	constructor(providers) {
+		this.providers = providers;
+	}
+	static make(service, acquire) {
+		return new Layer([{
+			service,
+			acquire
+		}]);
+	}
+	static succeed(service, instance) {
+		return Layer.make(service, () => instance);
+	}
+	static scoped(service, acquire, release) {
+		return new Layer([{
+			service,
+			acquire,
+			release: (instance) => release(instance)
+		}]);
+	}
+	static merge(...layers) {
+		const providers = /* @__PURE__ */ new Map();
+		for (const layer of layers) for (const provider of layer.providers) {
+			const service = provider.service;
+			if (providers.has(service)) throw new Error(`Duplicate service "${service.name}" in Layer.merge()`);
+			providers.set(service, provider);
+		}
+		return new Layer([...providers.values()]);
+	}
+	static override(base, ...overrides) {
+		const providers = /* @__PURE__ */ new Map();
+		for (const provider of base.providers) providers.set(provider.service, provider);
+		for (const layer of overrides) for (const provider of layer.providers) providers.set(provider.service, provider);
+		return new Layer([...providers.values()]);
+	}
+};
+//#endregion
+//#region src/layer/runtime.ts
+const buildLayer = async (layer, backend) => {
+	for (const provider of layer.providers) await backend.register(provider);
+	ServiceRuntime.configure(backend);
+	return { async dispose() {
+		try {
+			await backend.disposeAll();
+		} finally {
+			ServiceRuntime.reset();
+		}
+	} };
+};
+var RuntimeLayer = class {
+	static build = buildLayer;
+};
+//#endregion
+//#region src/resource/errors.ts
+var ResourceReleaseFailure = class extends TaggedError("ResourceReleaseFailure") {};
+//#endregion
+//#region src/resource/internal.ts
+const disposeResource = (resource) => {
+	const candidate = Object(resource);
+	return (candidate[Symbol.asyncDispose] ?? candidate[Symbol.dispose])?.call(candidate);
+};
+const toReleaseFailure = (resource, cause) => new ResourceReleaseFailure({
+	resource,
+	cause,
+	message: `Failed to release resource: ${resource}`
+});
+/**
+* Executa uma operação que retorna Result e converte
+* exceptions/rejections inesperadas para UnhandledException.
+*/
+const runResult = async (operation) => {
+	return (await Result.tryPromise(() => Promise.resolve(operation()))).andThen((result) => result);
+};
+const normalizeReleaseOutcome = (name, outcome) => {
+	if (outcome === void 0) return Result.ok();
+	return outcome.mapError((cause) => toReleaseFailure(name, cause));
+};
+const runRelease = async (name, resource, release) => {
+	return (await Result.tryPromise({
+		try: () => Promise.resolve(release(resource)),
+		catch: (cause) => toReleaseFailure(name, cause)
+	})).andThen((outcome) => normalizeReleaseOutcome(name, outcome));
+};
+/**
+* Precedência:
+*
+* 1. erro ocorrido durante use
+* 2. erro ocorrido durante release
+* 3. valor produzido por use
+*/
+const combineUseAndRelease = (used, released) => used.andThen((value) => released.map(() => value));
+//#endregion
+//#region src/resource/resource.ts
+const acquireUseRelease = ({ name, acquire, use, release = disposeResource }) => Result.gen(async function* () {
+	const resource = yield* Result.await(runResult(acquire));
+	/**
+	* Não usamos yield* aqui.
+	*
+	* Se use retornar Err, o generator seria
+	* encerrado imediatamente e o release
+	* nunca seria executado.
+	*/
+	const used = await runResult(() => use(resource));
+	const released = await runRelease(name, resource, release);
+	return combineUseAndRelease(used, released);
+});
+const Resource = { acquireUseRelease };
+//#endregion
+export { ItiLayerBackend, Layer, Resource, ResourceReleaseFailure, RuntimeLayer, Service, ServiceRuntime, buildLayer };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/service/runtime.ts","../src/service/service.ts","../src/layer/layer.ts","../src/layer/runtime.ts","../src/resource/errors.ts","../src/resource/internal.ts","../src/resource/resource.ts"],"sourcesContent":["import type { AnyServiceToken } from './types'\n\nexport interface ServiceResolver {\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>\n}\n\nlet currentResolver: ServiceResolver | undefined\n\nexport class ServiceRuntime {\n  static configure(resolver: ServiceResolver): void {\n    currentResolver = resolver\n  }\n\n  static async resolve<T extends AnyServiceToken>(token: T): Promise<InstanceType<T>> {\n    if (!currentResolver) {\n      throw new Error('ServiceRuntime has not been configured')\n    }\n\n    return await currentResolver.resolve(token)\n  }\n\n  static reset(): void {\n    currentResolver = undefined\n  }\n}\n","import { ServiceRuntime } from './runtime'\n\nimport type { ServiceToken } from './types'\n\nexport function Service<Self>() {\n  return class {\n    // oxlint-disable-next-line require-yield\n    static async *[Symbol.asyncIterator](): AsyncGenerator<never, Self, unknown> {\n      return await ServiceRuntime.resolve(this as unknown as ServiceToken<Self>)\n    }\n  }\n}\n","import type { ServiceClass } from '../service/types'\n\nimport type { LayerProvider, MaybePromise } from './types'\n\nexport class Layer {\n  private constructor(readonly providers: readonly LayerProvider[]) {}\n\n  static make<S extends ServiceClass<any>>(\n    service: S,\n    acquire: () => MaybePromise<InstanceType<S>>\n  ): Layer {\n    return new Layer([\n      {\n        service,\n        acquire\n      }\n    ])\n  }\n\n  static succeed<S extends ServiceClass<any>>(service: S, instance: InstanceType<S>): Layer {\n    return Layer.make(service, () => instance)\n  }\n\n  static scoped<S extends ServiceClass<any>>(\n    service: S,\n    acquire: () => MaybePromise<InstanceType<S>>,\n    release: (instance: InstanceType<S>) => MaybePromise<void>\n  ): Layer {\n    return new Layer([\n      {\n        service,\n        acquire,\n\n        release: (instance) => release(instance as InstanceType<S>)\n      }\n    ])\n  }\n\n  static merge(...layers: readonly Layer[]): Layer {\n    const providers = new Map<ServiceClass<any>, LayerProvider>()\n\n    for (const layer of layers) {\n      for (const provider of layer.providers) {\n        const service = provider.service\n\n        if (providers.has(service)) {\n          throw new Error(`Duplicate service \"${service.name}\" in Layer.merge()`)\n        }\n\n        providers.set(service, provider)\n      }\n    }\n\n    return new Layer([...providers.values()])\n  }\n\n  static override(base: Layer, ...overrides: readonly Layer[]): Layer {\n    const providers = new Map<ServiceClass<any>, LayerProvider>()\n\n    for (const provider of base.providers) {\n      providers.set(provider.service, provider)\n    }\n\n    for (const layer of overrides) {\n      for (const provider of layer.providers) {\n        providers.set(provider.service, provider)\n      }\n    }\n\n    return new Layer([...providers.values()])\n  }\n}\n","import { ServiceRuntime } from '../service/runtime'\n\nimport type { LayerBackend } from './backend'\nimport type { Layer } from './layer'\n\nexport interface BuiltLayer {\n  dispose(): Promise<void>\n}\n\nexport const buildLayer = async (layer: Layer, backend: LayerBackend): Promise<BuiltLayer> => {\n  for (const provider of layer.providers) {\n    await backend.register(provider)\n  }\n\n  ServiceRuntime.configure(backend)\n\n  return {\n    async dispose() {\n      try {\n        await backend.disposeAll()\n      } finally {\n        ServiceRuntime.reset()\n      }\n    }\n  }\n}\n\nexport class RuntimeLayer {\n  static build = buildLayer\n}\n","import { TaggedError } from 'better-result'\n\nexport class ResourceReleaseFailure extends TaggedError('ResourceReleaseFailure')<{\n  readonly resource: string\n  readonly cause: unknown\n  readonly message: string\n}> {}\n","import { Result, type Result as ResultType, type UnhandledException } from 'better-result'\n\nimport { ResourceReleaseFailure } from './errors'\n\nimport type { AsyncResult, DisposableResource, MaybePromise, ReleaseOutcome } from './types'\n\nexport const disposeResource = (resource: unknown): MaybePromise<void> => {\n  const candidate = Object(resource) as DisposableResource\n\n  const dispose = candidate[Symbol.asyncDispose] ?? candidate[Symbol.dispose]\n\n  return dispose?.call(candidate)\n}\n\nconst toReleaseFailure = (resource: string, cause: unknown): ResourceReleaseFailure =>\n  new ResourceReleaseFailure({\n    resource,\n    cause,\n    message: `Failed to release resource: ${resource}`\n  })\n\n/**\n * Executa uma operação que retorna Result e converte\n * exceptions/rejections inesperadas para UnhandledException.\n */\nexport const runResult = async <T, E>(\n  operation: () => AsyncResult<T, E>\n): Promise<ResultType<T, E | UnhandledException>> => {\n  const execution = await Result.tryPromise(() => Promise.resolve(operation()))\n\n  return execution.andThen((result) => result)\n}\n\nconst normalizeReleaseOutcome = (\n  name: string,\n  outcome: ReleaseOutcome\n): ResultType<void, ResourceReleaseFailure> => {\n  if (outcome === undefined) {\n    return Result.ok()\n  }\n\n  return outcome.mapError((cause) => toReleaseFailure(name, cause))\n}\n\nexport const runRelease = async <R>(\n  name: string,\n  resource: R,\n  release: (resource: R) => MaybePromise<ReleaseOutcome>\n): Promise<ResultType<void, ResourceReleaseFailure>> => {\n  const execution = await Result.tryPromise({\n    try: () => Promise.resolve(release(resource)),\n\n    catch: (cause) => toReleaseFailure(name, cause)\n  })\n\n  return execution.andThen((outcome) => normalizeReleaseOutcome(name, outcome))\n}\n\n/**\n * Precedência:\n *\n * 1. erro ocorrido durante use\n * 2. erro ocorrido durante release\n * 3. valor produzido por use\n */\nexport const combineUseAndRelease = <A, E>(\n  used: ResultType<A, E>,\n  released: ResultType<void, ResourceReleaseFailure>\n): ResultType<A, E | ResourceReleaseFailure> => used.andThen((value) => released.map(() => value))\n","import { Result, type Result as ResultType, type UnhandledException } from 'better-result'\n\nimport { ResourceReleaseFailure } from './errors'\n\nimport { combineUseAndRelease, disposeResource, runRelease, runResult } from './internal'\n\nimport type { AcquireUseReleaseOptions } from './types'\n\nconst acquireUseRelease = <R, A, AcquireError, UseError>({\n  name,\n  acquire,\n  use,\n  release = disposeResource\n}: AcquireUseReleaseOptions<R, A, AcquireError, UseError>): Promise<\n  ResultType<A, AcquireError | UseError | UnhandledException | ResourceReleaseFailure>\n> =>\n  Result.gen(async function* () {\n    const resource = yield* Result.await(runResult(acquire))\n\n    /**\n     * Não usamos yield* aqui.\n     *\n     * Se use retornar Err, o generator seria\n     * encerrado imediatamente e o release\n     * nunca seria executado.\n     */\n    const used = await runResult(() => use(resource))\n\n    const released = await runRelease(name, resource, release)\n\n    return combineUseAndRelease(used, released)\n  })\n\nexport const Resource = {\n  acquireUseRelease\n} as const\n"],"mappings":"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"}

package/dist/iti-xXAb9-Qs.d.mts

@@ -0,0 +1,45 @@
+//#region src/service/types.d.ts
+type ServiceToken<A = unknown> = (abstract new (...args: any[]) => A) & {
+  readonly name: string;
+};
+type ServiceClass<A = unknown> = ServiceToken<A>;
+type AnyServiceToken = ServiceToken<any>;
+type ServiceInstance<T extends AnyServiceToken> = InstanceType<T>;
+//#endregion
+//#region src/layer/types.d.ts
+type MaybePromise<T> = T | PromiseLike<T>;
+interface LayerProvider {
+  readonly service: ServiceClass<any>;
+  readonly acquire: () => MaybePromise<unknown>;
+  readonly release?: (instance: unknown) => MaybePromise<void>;
+}
+//#endregion
+//#region src/service/runtime.d.ts
+interface ServiceResolver {
+  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
+}
+declare class ServiceRuntime {
+  static configure(resolver: ServiceResolver): void;
+  static resolve<T extends AnyServiceToken>(token: T): Promise<InstanceType<T>>;
+  static reset(): void;
+}
+//#endregion
+//#region src/layer/backend.d.ts
+interface LayerBackend extends ServiceResolver {
+  register(provider: LayerProvider): void | PromiseLike<void>;
+  disposeAll(): void | PromiseLike<void>;
+}
+//#endregion
+//#region src/adapters/iti.d.ts
+declare class ItiLayerBackend implements LayerBackend {
+  private container;
+  private readonly keys;
+  private nextId;
+  private keyFor;
+  register(provider: LayerProvider): void;
+  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
+  disposeAll(): Promise<void>;
+}
+//#endregion
+export { LayerProvider as a, ServiceClass as c, ServiceRuntime as i, ServiceInstance as l, LayerBackend as n, MaybePromise as o, ServiceResolver as r, AnyServiceToken as s, ItiLayerBackend as t };
+//# sourceMappingURL=iti-xXAb9-Qs.d.mts.map

package/dist/iti-xXAb9-Qs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iti-xXAb9-Qs.d.mts","names":[],"sources":["../src/service/types.ts","../src/layer/types.ts","../src/service/runtime.ts","../src/layer/backend.ts","../src/adapters/iti.ts"],"mappings":";KAAY,aAAa,iCAAiC,gBAAgB;WAC/D;;KAGC,aAAa,eAAe,aAAa;KAEzC,kBAAkB;KAElB,gBAAgB,UAAU,mBAAmB,aAAa;;;KCN1D,aAAa,KAAK,IAAI,YAAY;UAE7B;WACN,SAAS;WAET,eAAe;WAEf,WAAW,sBAAsB;;;;UCP3B;EACf,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;cAK9E;SACJ,UAAU,UAAU;SAId,QAAQ,UAAU,iBAAiB,OAAO,IAAI,QAAQ,aAAa;SAQzE;;;;UCjBQ,qBAAqB;EACpC,SAAS,UAAU,uBAAuB;EAE1C,qBAAqB;;;;cCAV,2BAA2B;UAC9B;mBAES;UAET;UAEA;EAgBR,SAAS,UAAU;EAcnB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;EAMnF,cAAc"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "better-effect",
+  "version": "0.1.0",
+  "description": "Lightweight Effect-inspired primitives for better-result",
+  "keywords": [
+    "better-result",
+    "dependency-injection",
+    "effect",
+    "layer",
+    "resource",
+    "result",
+    "typescript"
+  ],
+  "homepage": "https://github.com/nitoba/better-effect#readme",
+  "bugs": {
+    "url": "https://github.com/nitoba/better-effect/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitoba/better-effect.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./adapters/iti": "./dist/adapters/iti.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "oxlint --type-aware .",
+    "lint:fix": "oxlint --type-aware --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt .",
+    "publint": "publint",
+    "check": "bun run typecheck && bun test && bun run lint && bun run format:check && bun run build && bun run publint",
+    "prepublishOnly": "bun run check",
+    "release:dry": "bun publish --dry-run"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "iti": "^0.8.0",
+    "lefthook": "^2.1.10",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "publint": "^0.3.23",
+    "tsdown": "^0.22.14"
+  },
+  "peerDependencies": {
+    "better-result": "^3.0.0",
+    "iti": "^0.8.0",
+    "typescript": "^7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "iti": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "iti": "^0.8.0"
+  }
+}