better-effect 0.4.0 → 0.5.0

package/README.md

@@ -16,13 +16,13 @@ bun add better-effect better-result
 import { Result } from 'better-result'
 import { Effect, Layer, Runtime, Service } from 'better-effect'
 
-class Database extends Service<Database>() {
+class Database extends Service<Database>()('Database') {
   findUser(id: string) {
     // ...
   }
 }
 
-class UserRepository extends Service<UserRepository>() {
+class UserRepository extends Service<UserRepository>()('UserRepository') {
   findUser(id: string) {
     return Effect.gen(async function* () {
       const database = yield* Database
@@ -32,21 +32,46 @@ class UserRepository extends Service<UserRepository>() {
   }
 }
 
-const UserRepositoryLive = Layer.make(UserRepository, () => new UserRepository())
+const UserRepositoryLive = Layer.make(UserRepository)
 
 await Runtime.make(UserRepositoryLive, backend)
 //                 ^^^^^^^^^^^^^^^^^^
 // Type error: Database is required but not provided
 ```
 
+The explicit self type keeps `yield*` inference exact, while the non-empty
+literal is the Service's stable logical identity. Services with identical
+methods but different tags are different dependencies; use a namespaced tag
+such as `@acme/Database` when identities must be shared across packages.
+
 `UserRepository` used `Database`, so `Database` became part of its environment requirements.
 
 No dependency list was written manually.
 
+Services can also describe a contract without requiring a class instance. Use the
+static `of` helper to type-check a structural implementation; it returns the same
+object unchanged at runtime:
+
+```ts
+class Authorization extends Service<Authorization>()('Authorization') {
+  declare readonly authorize: (token: string) => Promise<boolean>
+}
+
+const authorization = Authorization.of({
+  authorize: async (token) => token.length > 0
+})
+
+const AuthorizationLive = Layer.succeed(Authorization, authorization)
+```
+
+`Authorization.of(...)` does not call a constructor or make the result an
+`instanceof Authorization`. For services with constructors, private fields or
+other runtime invariants, use `new Authorization(...)` instead.
+
 Provide it and the environment becomes complete:
 
 ```ts
-const DatabaseLive = Layer.make(Database, () => new Database())
+const DatabaseLive = Layer.make(Database)
 
 const AppLive = Layer.merge(DatabaseLive, UserRepositoryLive)
 
@@ -264,7 +289,9 @@ const program = pipe(
 
 The combinators keep the `better-result` semantics: `Effect.map` changes the success
 type, `Effect.mapError` changes the error type, and `Effect.andThen` only calls the next
-step after an `Ok`. The pipeline carries the requirements of every step, so Runtime
+step after an `Ok`. Use `Effect.andThenAsync` when the next operation returns a
+`Promise<Result>`; it always returns a Promise, including when the source is synchronous
+or already an `Err`. The pipeline carries the requirements of every step, so Runtime
 still rejects it when its Layer does not provide every required Service.
 
 Use `Effect.gen` for larger workflows with several intermediate values, branches or

package/dist/adapters/iti.d.mts

@@ -1,13 +1,21 @@
-import { V as AnyServiceToken, t as LayerBackend, v as LayerProvider } from "../index-BYQKfyeJ.mjs";
+import { V as AnyServiceToken, t as LayerBackend, v as LayerRegistration } from "../index-D77AvuBl.mjs";
 //#region src/adapters/iti.d.ts
+/**
+ * ITI-backed Layer backend.
+ *
+ * Install `iti` as the optional peer dependency and pass an instance to
+ * `Runtime.make` when using ITI's container implementation.
+ */
 declare class ItiLayerBackend implements LayerBackend {
   private container;
   private readonly keys;
   private readonly registered;
-  private nextId;
   private keyFor;
-  register(provider: LayerProvider): void;
+  /** Register a Layer provider under its deterministic Service-tag key. */
+  register(registration: LayerRegistration): void;
+  /** Resolve a registered Service through the ITI container. */
   resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>>;
+  /** Dispose all ITI-managed provider instances. */
   disposeAll(): Promise<void>;
 }
 //#endregion

package/dist/adapters/iti.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;cAMa,2BAA2B;UAC9B;mBAES;mBAEA;UAET;UAEA;EAgBR,SAAS,UAAU;EAgBnB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;EAUnF,cAAc"}
+{"version":3,"file":"iti.d.mts","names":[],"sources":["../../src/adapters/iti.ts"],"mappings":";;;;;;;;cAmBa,2BAA2B;UAC9B;mBAES;mBAEA;UAET;;EAgBR,SAAS,cAAc;;EAuBvB,QAAQ,UAAU,iBAAiB,OAAO,IAAI,aAAa,KAAK,YAAY,aAAa;;EAuBnF,cAAc"}

package/dist/adapters/iti.mjs

@@ -1,30 +1,50 @@
-import { n as DuplicateServiceError, o as ServiceNotFoundError } from "../errors-DlHCwICc.mjs";
+import { a as ServiceTagCollisionError, o as ServiceNotFoundError, t as DuplicateServiceError } from "../errors-GR3K_nRu.mjs";
+import { t as assertServiceCompatibility } from "../internal-identity-BnZC3Au-.mjs";
 import { createContainer } from "iti";
 //#region src/adapters/iti.ts
+/**
+* ITI-backed Layer backend.
+*
+* Install `iti` as the optional peer dependency and pass an instance to
+* `Runtime.make` when using ITI's container implementation.
+*/
 var ItiLayerBackend = class {
 	container = createContainer();
-	keys = /* @__PURE__ */ new WeakMap();
-	registered = /* @__PURE__ */ new WeakSet();
-	nextId = 0;
+	keys = /* @__PURE__ */ new Map();
+	registered = /* @__PURE__ */ new Map();
 	keyFor(token) {
-		const existing = this.keys.get(token);
+		const tag = token.serviceTag;
+		const existing = this.keys.get(tag);
 		if (existing) return existing;
-		const key = `better-effect:${token.name || "Service"}:${this.nextId++}`;
-		this.keys.set(token, key);
+		const key = `better-effect:${tag}`;
+		this.keys.set(tag, key);
 		return key;
 	}
-	register(provider) {
-		const token = provider.service;
-		if (this.registered.has(token)) throw new DuplicateServiceError(token);
+	/** Register a Layer provider under its deterministic Service-tag key. */
+	register(registration) {
+		const token = registration.service;
+		const tag = token.serviceTag;
+		const existing = this.registered.get(tag);
+		if (existing === token) throw new DuplicateServiceError(token);
+		if (existing) throw new ServiceTagCollisionError(existing, token);
 		const key = this.keyFor(token);
-		this.container = this.container.add({ [key]: provider.acquire });
-		this.registered.add(token);
+		this.container = this.container.add({ [key]: registration.acquire });
+		this.registered.set(tag, token);
 	}
+	/** Resolve a registered Service through the ITI container. */
 	resolve(token) {
-		if (!this.registered.has(token)) throw new ServiceNotFoundError(token);
+		if (!this.registered.has(token.serviceTag)) throw new ServiceNotFoundError(token);
+		const registered = this.registered.get(token.serviceTag);
 		const key = this.keyFor(token);
-		return this.container.get(key);
+		const resolved = this.container.get(key);
+		const validate = (instance) => {
+			assertServiceCompatibility(token, registered, instance);
+			return instance;
+		};
+		if (resolved && typeof resolved.then === "function") return Promise.resolve(resolved).then(validate);
+		return validate(resolved);
 	}
+	/** Dispose all ITI-managed provider instances. */
 	async disposeAll() {
 		await this.container.disposeAll();
 	}

package/dist/adapters/iti.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport { DuplicateServiceError, type LayerBackend, type LayerProvider } from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\n\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new WeakMap<AnyServiceToken, string>()\n\n  private readonly registered = new WeakSet<AnyServiceToken>()\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.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 token = provider.service\n\n    if (this.registered.has(token)) {\n      throw new DuplicateServiceError(token)\n    }\n\n    const key = this.keyFor(token)\n\n    this.container = this.container.add({\n      [key]: provider.acquire\n    })\n\n    this.registered.add(token)\n  }\n\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    if (!this.registered.has(token)) {\n      throw new ServiceNotFoundError(token)\n    }\n\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":";;;AAMA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,QAAiC;CAE7D,6BAA8B,IAAI,QAAyB;CAE3D,SAAiB;CAEjB,OAAe,OAAgC;EAC7C,MAAM,WAAW,KAAK,KAAK,IAAI,KAAK;EAEpC,IAAI,UACF,OAAO;EAKT,MAAM,MAAM,iBAFC,MAAM,QAAQ,UAEO,GAAG,KAAK;EAE1C,KAAK,KAAK,IAAI,OAAO,GAAG;EAExB,OAAO;CACT;CAEA,SAAS,UAA+B;EACtC,MAAM,QAAQ,SAAS;EAEvB,IAAI,KAAK,WAAW,IAAI,KAAK,GAC3B,MAAM,IAAI,sBAAsB,KAAK;EAGvC,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,SAAS,QAClB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK;CAC3B;CAEA,QAAmC,OAA0D;EAC3F,IAAI,CAAC,KAAK,WAAW,IAAI,KAAK,GAC5B,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,OAAO,KAAK,UAAU,IAAI,GAAG;CAC/B;CAEA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;AACF"}
+{"version":3,"file":"iti.mjs","names":[],"sources":["../../src/adapters/iti.ts"],"sourcesContent":["import { createContainer } from 'iti'\n\nimport {\n  DuplicateServiceError,\n  ServiceTagCollisionError,\n  type LayerBackend,\n  type LayerRegistration\n} from '../layer'\n\nimport { ServiceNotFoundError, type AnyServiceToken } from '../service'\n\nimport { assertServiceCompatibility } from '../layer/internal-identity'\n\n/**\n * ITI-backed Layer backend.\n *\n * Install `iti` as the optional peer dependency and pass an instance to\n * `Runtime.make` when using ITI's container implementation.\n */\nexport class ItiLayerBackend implements LayerBackend {\n  private container: any = createContainer()\n\n  private readonly keys = new Map<string, string>()\n\n  private readonly registered = new Map<string, AnyServiceToken>()\n\n  private keyFor(token: AnyServiceToken): string {\n    const tag = token.serviceTag\n    const existing = this.keys.get(tag)\n\n    if (existing) {\n      return existing\n    }\n\n    const key = `better-effect:${tag}`\n\n    this.keys.set(tag, key)\n\n    return key\n  }\n\n  /** Register a Layer provider under its deterministic Service-tag key. */\n  register(registration: LayerRegistration): void {\n    const token = registration.service\n    const tag = token.serviceTag\n    const existing = this.registered.get(tag)\n\n    if (existing === token) {\n      throw new DuplicateServiceError(token)\n    }\n\n    if (existing) {\n      throw new ServiceTagCollisionError(existing, token)\n    }\n\n    const key = this.keyFor(token)\n\n    this.container = this.container.add({\n      [key]: registration.acquire\n    })\n\n    this.registered.set(tag, token)\n  }\n\n  /** Resolve a registered Service through the ITI container. */\n  resolve<T extends AnyServiceToken>(token: T): InstanceType<T> | PromiseLike<InstanceType<T>> {\n    if (!this.registered.has(token.serviceTag)) {\n      throw new ServiceNotFoundError(token)\n    }\n\n    const registered = this.registered.get(token.serviceTag)\n    const key = this.keyFor(token)\n    const resolved = this.container.get(key) as unknown\n\n    const validate = (instance: unknown): InstanceType<T> => {\n      assertServiceCompatibility(token, registered!, instance)\n\n      return instance as InstanceType<T>\n    }\n\n    if (resolved && typeof (resolved as PromiseLike<unknown>).then === 'function') {\n      return Promise.resolve(resolved).then(validate)\n    }\n\n    return validate(resolved)\n  }\n\n  /** Dispose all ITI-managed provider instances. */\n  async disposeAll(): Promise<void> {\n    await this.container.disposeAll()\n  }\n}\n"],"mappings":";;;;;;;;;;AAmBA,IAAa,kBAAb,MAAqD;CACnD,YAAyB,gBAAgB;CAEzC,uBAAwB,IAAI,IAAoB;CAEhD,6BAA8B,IAAI,IAA6B;CAE/D,OAAe,OAAgC;EAC7C,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,KAAK,IAAI,GAAG;EAElC,IAAI,UACF,OAAO;EAGT,MAAM,MAAM,iBAAiB;EAE7B,KAAK,KAAK,IAAI,KAAK,GAAG;EAEtB,OAAO;CACT;;CAGA,SAAS,cAAuC;EAC9C,MAAM,QAAQ,aAAa;EAC3B,MAAM,MAAM,MAAM;EAClB,MAAM,WAAW,KAAK,WAAW,IAAI,GAAG;EAExC,IAAI,aAAa,OACf,MAAM,IAAI,sBAAsB,KAAK;EAGvC,IAAI,UACF,MAAM,IAAI,yBAAyB,UAAU,KAAK;EAGpD,MAAM,MAAM,KAAK,OAAO,KAAK;EAE7B,KAAK,YAAY,KAAK,UAAU,IAAI,GACjC,MAAM,aAAa,QACtB,CAAC;EAED,KAAK,WAAW,IAAI,KAAK,KAAK;CAChC;;CAGA,QAAmC,OAA0D;EAC3F,IAAI,CAAC,KAAK,WAAW,IAAI,MAAM,UAAU,GACvC,MAAM,IAAI,qBAAqB,KAAK;EAGtC,MAAM,aAAa,KAAK,WAAW,IAAI,MAAM,UAAU;EACvD,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,MAAM,WAAW,KAAK,UAAU,IAAI,GAAG;EAEvC,MAAM,YAAY,aAAuC;GACvD,2BAA2B,OAAO,YAAa,QAAQ;GAEvD,OAAO;EACT;EAEA,IAAI,YAAY,OAAQ,SAAkC,SAAS,YACjE,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,QAAQ;EAGhD,OAAO,SAAS,QAAQ;CAC1B;;CAGA,MAAM,aAA4B;EAChC,MAAM,KAAK,UAAU,WAAW;CAClC;AACF"}

package/dist/errors-GR3K_nRu.mjs

@@ -0,0 +1,74 @@
+//#region src/service/errors.ts
+/** Thrown when a Service is accessed without an active runtime resolver. */
+var ServiceRuntimeNotConfiguredError = class extends Error {
+	constructor() {
+		super("No ServiceResolver is available in the current runtime context");
+		this.name = "ServiceRuntimeNotConfiguredError";
+	}
+};
+/** Thrown when a runtime has no provider for the requested Service tag. */
+var ServiceNotFoundError = class extends Error {
+	service;
+	constructor(service) {
+		super(`Service "${service.serviceTag}" was not provided`);
+		this.service = service;
+		this.name = "ServiceNotFoundError";
+	}
+};
+//#endregion
+//#region src/layer/errors.ts
+/** Thrown when a Layer registers the same Service tag more than once. */
+var DuplicateServiceError = class extends Error {
+	service;
+	constructor(service) {
+		super(`Duplicate service tag "${service.serviceTag}"`);
+		this.service = service;
+		this.name = "DuplicateServiceError";
+	}
+};
+/** Thrown when one Service tag is associated with incompatible constructors. */
+var ServiceTagCollisionError = class extends Error {
+	existing;
+	incoming;
+	constructor(existing, incoming) {
+		super(`Service tag "${incoming.serviceTag}" is already associated with "${existing.name}" and cannot be associated with "${incoming.name}"`);
+		this.existing = existing;
+		this.incoming = incoming;
+		this.name = "ServiceTagCollisionError";
+	}
+};
+/** Thrown when a backend fails while registering a Layer provider. */
+var LayerRegistrationError = class extends Error {
+	service;
+	registrationCause;
+	cleanupCause;
+	constructor(service, registrationCause, cleanupCause) {
+		super(service ? `Failed to register service "${service.serviceTag}"` : "Failed to build Layer", { cause: registrationCause });
+		this.service = service;
+		this.registrationCause = registrationCause;
+		this.cleanupCause = cleanupCause;
+		this.name = "LayerRegistrationError";
+	}
+};
+/** Thrown when one or more Layer-owned resources fail during disposal. */
+var LayerDisposeError = class extends Error {
+	causes;
+	constructor(causes) {
+		super(`Failed to dispose Layer (${causes.length} error${causes.length === 1 ? "" : "s"})`);
+		this.causes = causes;
+		this.name = "LayerDisposeError";
+	}
+};
+/** Thrown when a Layer generator yields a value other than a Service requirement. */
+var LayerGeneratorYieldError = class extends Error {
+	service;
+	constructor(service) {
+		super(`Layer.gen("${service.serviceTag}") yielded an unsupported value`);
+		this.service = service;
+		this.name = "LayerGeneratorYieldError";
+	}
+};
+//#endregion
+export { ServiceTagCollisionError as a, LayerRegistrationError as i, LayerDisposeError as n, ServiceNotFoundError as o, LayerGeneratorYieldError as r, ServiceRuntimeNotConfiguredError as s, DuplicateServiceError as t };
+
+//# sourceMappingURL=errors-GR3K_nRu.mjs.map

package/dist/errors-GR3K_nRu.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-GR3K_nRu.mjs","names":[],"sources":["../src/service/errors.ts","../src/layer/errors.ts"],"sourcesContent":["import type { AnyServiceToken } from './types'\n\n/** Thrown when a Service is accessed without an active runtime resolver. */\nexport class ServiceRuntimeNotConfiguredError extends Error {\n  constructor() {\n    super('No ServiceResolver is available in the current runtime context')\n\n    this.name = 'ServiceRuntimeNotConfiguredError'\n  }\n}\n\n/** Thrown when a runtime has no provider for the requested Service tag. */\nexport class ServiceNotFoundError extends Error {\n  constructor(readonly service: AnyServiceToken) {\n    super(`Service \"${service.serviceTag}\" was not provided`)\n\n    this.name = 'ServiceNotFoundError'\n  }\n}\n","import type { AnyServiceToken, ServiceClass } from '../service'\n\n/** Thrown when a Layer registers the same Service tag more than once. */\nexport class DuplicateServiceError extends Error {\n  constructor(readonly service: ServiceClass<any>) {\n    super(`Duplicate service tag \"${service.serviceTag}\"`)\n\n    this.name = 'DuplicateServiceError'\n  }\n}\n\n/** Thrown when one Service tag is associated with incompatible constructors. */\nexport class ServiceTagCollisionError extends Error {\n  constructor(\n    readonly existing: AnyServiceToken,\n    readonly incoming: AnyServiceToken\n  ) {\n    super(\n      `Service tag \"${incoming.serviceTag}\" is already associated with \"${existing.name}\" ` +\n        `and cannot be associated with \"${incoming.name}\"`\n    )\n\n    this.name = 'ServiceTagCollisionError'\n  }\n}\n\n/** Thrown when a backend fails while registering a Layer provider. */\nexport class LayerRegistrationError extends Error {\n  constructor(\n    readonly service: ServiceClass<any> | undefined,\n    readonly registrationCause: unknown,\n    readonly cleanupCause?: unknown\n  ) {\n    super(\n      service ? `Failed to register service \"${service.serviceTag}\"` : 'Failed to build Layer',\n      {\n        cause: registrationCause\n      }\n    )\n\n    this.name = 'LayerRegistrationError'\n  }\n}\n\n/** Thrown when one or more Layer-owned resources fail during disposal. */\nexport class LayerDisposeError extends Error {\n  constructor(readonly causes: readonly unknown[]) {\n    super(`Failed to dispose Layer (${causes.length} error${causes.length === 1 ? '' : 's'})`)\n\n    this.name = 'LayerDisposeError'\n  }\n}\n\n/** Thrown when a Layer generator yields a value other than a Service requirement. */\nexport class LayerGeneratorYieldError extends Error {\n  constructor(readonly service: ServiceClass<any>) {\n    super(`Layer.gen(\"${service.serviceTag}\") yielded an unsupported value`)\n\n    this.name = 'LayerGeneratorYieldError'\n  }\n}\n"],"mappings":";;AAGA,IAAa,mCAAb,cAAsD,MAAM;CAC1D,cAAc;EACZ,MAAM,gEAAgE;EAEtE,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,uBAAb,cAA0C,MAAM;CACzB;CAArB,YAAY,SAAmC;EAC7C,MAAM,YAAY,QAAQ,WAAW,mBAAmB;EADrC,KAAA,UAAA;EAGnB,KAAK,OAAO;CACd;AACF;;;;ACfA,IAAa,wBAAb,cAA2C,MAAM;CAC1B;CAArB,YAAY,SAAqC;EAC/C,MAAM,0BAA0B,QAAQ,WAAW,EAAE;EADlC,KAAA,UAAA;EAGnB,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,2BAAb,cAA8C,MAAM;CAEvC;CACA;CAFX,YACE,UACA,UACA;EACA,MACE,gBAAgB,SAAS,WAAW,gCAAgC,SAAS,KAAK,mCAC9C,SAAS,KAAK,EACpD;EANS,KAAA,WAAA;EACA,KAAA,WAAA;EAOT,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,yBAAb,cAA4C,MAAM;CAErC;CACA;CACA;CAHX,YACE,SACA,mBACA,cACA;EACA,MACE,UAAU,+BAA+B,QAAQ,WAAW,KAAK,yBACjE,EACE,OAAO,kBACT,CACF;EATS,KAAA,UAAA;EACA,KAAA,oBAAA;EACA,KAAA,eAAA;EAST,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,oBAAb,cAAuC,MAAM;CACtB;CAArB,YAAY,QAAqC;EAC/C,MAAM,4BAA4B,OAAO,OAAO,QAAQ,OAAO,WAAW,IAAI,KAAK,IAAI,EAAE;EADtE,KAAA,SAAA;EAGnB,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,2BAAb,cAA8C,MAAM;CAC7B;CAArB,YAAY,SAAqC;EAC/C,MAAM,cAAc,QAAQ,WAAW,gCAAgC;EADpD,KAAA,UAAA;EAGnB,KAAK,OAAO;CACd;AACF"}