@crustjs/effect 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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

@@ -0,0 +1,51 @@
+# @crustjs/effect
+
+Effect.ts v4 adaptor for Crust: write Command Actions and Contexts in Effect idiom while Crust stays the runtime.
+
+## Install
+
+```sh
+bun add @crustjs/effect@next effect@4.0.0-rc.115
+```
+
+`effect` (4.x prerelease) and `@crustjs/core` are peer dependencies. Install the exact `effect` version this package was tested against; the adaptor is published under the `next` dist-tag.
+
+## Quick example
+
+```ts
+import { Crust, defineContext } from "@crustjs/core";
+import { handler, layer, service } from "@crustjs/effect";
+import { Context, Effect, Layer } from "effect";
+
+class Db extends Context.Service<Db, { readonly query: (sql: string) => string }>()("app/Db") {}
+
+const db = layer(
+	"db",
+	Layer.effect(
+		Db,
+		Effect.acquireRelease(
+			Effect.sync(() => ({ query: (sql) => `rows for ${sql}` })),
+			() => Effect.sync(() => console.log("closed")),
+		),
+	),
+);
+const config = defineContext("config", () => ({ limit: 10 }));
+
+await new Crust("app")
+	.provide(db(), config())
+	.args({ name: "table", type: "string", required: true })
+	.action(
+		handler(function* ({ args }) {
+			const d = yield* Db;
+			const cfg = yield* service(config);
+			console.log(d.query(`select * from ${args.table} limit ${cfg.limit}`));
+		}),
+	)
+	.execute();
+```
+
+Every `layer()` on the command path is built when the handler starts and released by Crust's cleanup; plain Contexts stay lazy. If `layer`/`handler` clash with names in your module, use `import * as CrustEffect from "@crustjs/effect"`.
+
+## Documentation
+
+Full docs: [crustjs.com/docs/modules/effect](https://crustjs.com/docs/modules/effect)

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { AnyContextFactory, ContextFactory, CrustCommandContext, CrustError, CrustErrorCode, CrustErrorDetails, FactoryValueOf } from "@crustjs/core";
+import { Cause, Context, Effect, Exit, Layer } from "effect";
+//#region src/errors.d.ts
+/** Fields shared by every tagged Crust error; `cause` keeps the original for rethrow. */
+interface CrustErrorFields<C extends CrustErrorCode> {
+  readonly message: string;
+  readonly details: CrustErrorDetails<C>;
+  readonly cause: CrustError<C>;
+}
+type TaggedCrustError<Tag extends string, C extends CrustErrorCode> = new (fields: CrustErrorFields<C>) => Cause.YieldableError & {
+  readonly _tag: Tag;
+} & CrustErrorFields<C>;
+declare const DefinitionBase: TaggedCrustError<"CrustDefinitionError", "DEFINITION">;
+declare const ValidationBase: TaggedCrustError<"CrustValidationError", "VALIDATION">;
+declare const ParseBase: TaggedCrustError<"CrustParseError", "PARSE">;
+declare const CommandNotFoundBase: TaggedCrustError<"CrustCommandNotFoundError", "COMMAND_NOT_FOUND">;
+export declare class CrustDefinitionError extends DefinitionBase {}
+export declare class CrustValidationError extends ValidationBase {}
+export declare class CrustParseError extends ParseBase {}
+export declare class CrustCommandNotFoundError extends CommandNotFoundBase {}
+type CrustTaggedError = CrustDefinitionError | CrustValidationError | CrustParseError | CrustCommandNotFoundError;
+/** Wrap a caught {@link CrustError} in the tagged class for its `code`. */
+export declare function fromCrustError(error: CrustError): CrustTaggedError;
+/**
+ * Lift a throwing thunk or promise into an Effect. A thrown `CrustError`
+ * fails with its tagged wrapper, an `AbortError` interrupts the fiber, and
+ * anything else is a defect.
+ */
+export declare function tryCrust<A>(evaluate: () => A | PromiseLike<A>): Effect.Effect<A, CrustTaggedError>;
+//#endregion
+//#region src/layer.d.ts
+declare const LayerBrand: unique symbol;
+/** A built Effect `Context.Context` produced by {@link layer}; the brand is type-only. */
+type LayerValue<S> = Context.Context<S> & {
+  readonly [LayerBrand]: true;
+};
+/**
+ * Turn one fully composed Layer into a Crust Context whose value is the built
+ * `Context.Context`. Every `layer()` on the command path is built when a
+ * `handler()` action starts and released, in reverse order, by Crust's
+ * invocation cleanup.
+ */
+export declare function layer<Name extends string, ROut, E>(name: Name, live: Layer.Layer<ROut, E>): ContextFactory<Name, void, LayerValue<ROut>>;
+//#endregion
+//#region src/handler.d.ts
+type ActionInput = CrustCommandContext<any, any, any>;
+declare const HandlerInputBase: Context.ServiceClass<HandlerInput, "@crustjs/effect/HandlerInput", ActionInput>;
+/** The invocation input, provided to every {@link handler} program so {@link service} can pull plain Contexts. */
+declare class HandlerInput extends HandlerInputBase {}
+/**
+ * Union of the services provided by the {@link layer} Contexts in an action
+ * input's `ctx` bag. Open-name bags (`Record<string, …>`) provide nothing:
+ * their entries cannot be tied to a layer on the path.
+ */
+type ServicesOf<Input> = Input extends {
+  readonly ctx: infer Bag;
+} ? string extends keyof Bag ? never : { [K in keyof Bag]-?: Bag[K] extends Promise<LayerValue<infer S>> ? S : never; }[keyof Bag] : never;
+/**
+ * Adapt an Effect program to a Crust action. Every {@link layer} on the
+ * command path is built up front and its services provided; `ctx` inference
+ * is unchanged. A failure rethrows the original error so `execute()` renders
+ * it unchanged, and interruption rethrows an `AbortError` so cancellation
+ * exits with 130.
+ */
+export declare function handler<Input extends ActionInput, Out, E>(fn: (input: Input) => Effect.Effect<Out, E, ServicesOf<Input> | HandlerInput>): (input: Input) => Promise<Out>;
+export declare function handler<Input extends ActionInput, Eff extends Effect.Effect<any, any, ServicesOf<Input> | HandlerInput>, Out>(fn: (input: Input) => Generator<Eff, Out, never>): (input: Input) => Promise<Out>;
+/**
+ * Pull a plain Crust Context by factory from inside a {@link handler} program.
+ * Lazy like `ctx.<name>`; a name absent from the command path fails with
+ * Core's missing-context error as a `CrustDefinitionError`.
+ */
+export declare function service<F extends AnyContextFactory>(factory: F): Effect.Effect<FactoryValueOf<F>, CrustTaggedError, HandlerInput>;
+//#endregion
+export type { CrustTaggedError, LayerValue, ServicesOf };

package/dist/index.js

@@ -0,0 +1,126 @@
+import { CrustError, contextSources, defineContext } from "@crustjs/core";
+import { Cause, Context, Data, Effect, Exit, Layer, Scope } from "effect";
+//#region src/errors.ts
+const tagged = (tag) => Data.TaggedError(tag);
+const DefinitionBase = tagged("CrustDefinitionError");
+const ValidationBase = tagged("CrustValidationError");
+const ParseBase = tagged("CrustParseError");
+const CommandNotFoundBase = tagged("CrustCommandNotFoundError");
+var CrustDefinitionError = class extends DefinitionBase {};
+var CrustValidationError = class extends ValidationBase {};
+var CrustParseError = class extends ParseBase {};
+var CrustCommandNotFoundError = class extends CommandNotFoundBase {};
+const fields = (error) => ({
+	message: error.message,
+	details: error.details,
+	cause: error
+});
+/** Wrap a caught {@link CrustError} in the tagged class for its `code`. */
+function fromCrustError(error) {
+	if (error.is("DEFINITION")) return new CrustDefinitionError(fields(error));
+	if (error.is("VALIDATION")) return new CrustValidationError(fields(error));
+	if (error.is("PARSE")) return new CrustParseError(fields(error));
+	return new CrustCommandNotFoundError(fields(error));
+}
+function isCrustTaggedError(value) {
+	return value instanceof CrustDefinitionError || value instanceof CrustValidationError || value instanceof CrustParseError || value instanceof CrustCommandNotFoundError;
+}
+/** Matches Core's cancellation check: prompts reject with a `DOMException` named `AbortError`. */
+function isAbortError(value) {
+	return value instanceof Error && value.name === "AbortError";
+}
+/**
+* Lift a throwing thunk or promise into an Effect. A thrown `CrustError`
+* fails with its tagged wrapper, an `AbortError` interrupts the fiber, and
+* anything else is a defect.
+*/
+function tryCrust(evaluate) {
+	return Effect.tryPromise({
+		try: () => Promise.resolve().then(evaluate),
+		catch: (error) => error
+	}).pipe(Effect.catch((error) => {
+		if (isAbortError(error)) return Effect.interrupt;
+		if (error instanceof CrustError) return Effect.fail(fromCrustError(error));
+		return Effect.die(error);
+	}));
+}
+/** Rethrow the original error behind a failed Cause so Core renders it unchanged. */
+function unwrapCause(cause) {
+	if (Cause.hasInterruptsOnly(cause)) throw new DOMException("Effect was interrupted.", "AbortError");
+	const error = Cause.squash(cause);
+	throw isCrustTaggedError(error) ? error.cause : error;
+}
+/** Return the success value; failures rethrow the original error, interruption an `AbortError`. */
+function unwrapExit(exit) {
+	if (Exit.isSuccess(exit)) return exit.value;
+	return unwrapCause(exit.cause);
+}
+//#endregion
+//#region src/layer.ts
+/** Factories created by {@link layer}, matched by identity so a same-named plain Context never counts. */
+const layerFactories = /* @__PURE__ */ new WeakSet();
+/**
+* Handler outcome per built Context, keyed by identity so nothing leaks across
+* invocations or applications. `Scope.close` hands it to finalizers, which may
+* branch on success versus failure/interruption (commit versus rollback).
+*/
+const actionExits = /* @__PURE__ */ new WeakMap();
+/**
+* Turn one fully composed Layer into a Crust Context whose value is the built
+* `Context.Context`. Every `layer()` on the command path is built when a
+* `handler()` action starts and released, in reverse order, by Crust's
+* invocation cleanup.
+*/
+function layer(name, live) {
+	const factory = defineContext(name, async ({ defer }) => {
+		const scope = Scope.makeUnsafe();
+		let built;
+		defer(() => Effect.runPromise(Scope.close(scope, (built && actionExits.get(built)) ?? Exit.void)));
+		built = unwrapExit(await Effect.runPromiseExit(Layer.buildWithScope(live, scope)));
+		return built;
+	});
+	layerFactories.add(factory);
+	return factory;
+}
+//#endregion
+//#region src/handler.ts
+const HandlerInputBase = Context.Service()("@crustjs/effect/HandlerInput");
+/** The invocation input, provided to every {@link handler} program so {@link service} can pull plain Contexts. */
+var HandlerInput = class extends HandlerInputBase {};
+function handler(fn) {
+	return async (input) => {
+		const layers = (input.ctx[contextSources] ?? []).filter((source) => "factory" in source && layerFactories.has(source.factory));
+		const bag = input.ctx;
+		const built = [];
+		const program = Effect.gen(function* () {
+			const settled = yield* Effect.promise(() => Promise.allSettled(layers.map(({ name }) => bag[name])));
+			for (const result of settled) if (result.status === "fulfilled") built.push(result.value);
+			const rejected = settled.find((result) => result.status === "rejected");
+			if (rejected) return yield* tryCrust(() => Promise.reject(rejected.reason));
+			const returned = fn(input);
+			return yield* Effect.provideContext(Effect.isEffect(returned) ? returned : Effect.gen(() => returned), Context.mergeAll(...built, Context.make(HandlerInput, input)));
+		});
+		const exit = await Effect.runPromiseExit(program);
+		for (const services of built) actionExits.set(services, exit);
+		return unwrapExit(exit);
+	};
+}
+/**
+* Pull a plain Crust Context by factory from inside a {@link handler} program.
+* Lazy like `ctx.<name>`; a name absent from the command path fails with
+* Core's missing-context error as a `CrustDefinitionError`.
+*/
+function service(factory) {
+	const name = factory.contextName;
+	return Effect.flatMap(HandlerInput, (input) => tryCrust(() => {
+		const bag = input.ctx;
+		if (Object.hasOwn(bag, name)) return bag[name];
+		throw new CrustError("DEFINITION", `No provider for Context "${name}". Add .provide(${name}(...)) to the app or an ancestor command.`, {
+			subject: "context",
+			name,
+			reason: "missing-context"
+		});
+	}));
+}
+//#endregion
+export { CrustCommandNotFoundError, CrustDefinitionError, CrustParseError, CrustValidationError, fromCrustError, handler, layer, service, tryCrust };

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@crustjs/effect",
+	"version": "0.0.0",
+	"description": "Effect.ts v4 adaptor for the Crust CLI framework: tagged errors, Effect actions, and Layer-backed Contexts",
+	"type": "module",
+	"sideEffects": false,
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/effect"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"effect",
+		"effect-ts",
+		"layer",
+		"crust",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"tag": "next"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test",
+		"prepack": "cp ../../LICENSE LICENSE",
+		"postpack": "rm -f LICENSE"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"@crustjs/core": "0.2.1",
+		"@crustjs/testing": "0.1.1",
+		"effect": "4.0.0-rc.115",
+		"tsdown": "^0.23.0"
+	},
+	"peerDependencies": {
+		"@crustjs/core": "^0.2.1",
+		"effect": "^4.0.0-rc.115",
+		"typescript": "^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"bun": ">=1.4.0",
+		"node": ">=22",
+		"deno": ">=2.8"
+	}
+}