@spaceteams/warp 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -13,24 +13,27 @@ type ComponentRef<Ctx, ScopeContext, RunOptions, Out> = {
   readonly __runOptions?: RunOptions;
   readonly __out?: Out;
 };
-type ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out> = (ctx: Run<Ctx & Deps, ScopeContext, RunOptions>) => Out;
+type ComponentKind = "repo" | "service" | "usecase" | "client";
+type ComponentMeta = {
+  name?: string;
+  kind?: ComponentKind;
+  tags?: string[];
+};
+type ComponentFactoryFn<Ctx, ScopeContext, RunOptions, Deps, Out> = (ctx: Run<Ctx & Deps, ScopeContext, RunOptions>) => Out;
+type ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out> = ComponentFactoryFn<Ctx, ScopeContext, RunOptions, Deps, Out> & {
+  meta?: ComponentMeta;
+};
 type ComponentInput<Ctx, ScopeContext, RunOptions, Out> = ComponentRef<Ctx, ScopeContext, RunOptions, Out> | Out;
 type Component<Ctx, ScopeContext, RunOptions, Deps, Out> = ComponentRef<Ctx, ScopeContext, RunOptions, Out> & {
   factory: ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out>;
   deps?: { [K in keyof Deps]: ComponentRef<Ctx, ScopeContext, RunOptions, Deps[K]> };
-  name?: string;
+  meta?: ComponentMeta;
 };
 type ComponentDefinition<Ctx, ScopeContext, RunOptions, Deps, Out> = {
   factory: ComponentFactory<Ctx, ScopeContext, RunOptions, Deps, Out>;
   deps?: { [K in keyof Deps]: ComponentInput<Ctx, ScopeContext, RunOptions, Deps[K]> };
-  name?: string;
+  meta?: ComponentMeta;
 };
-type InferComponentParams<T> = T extends Component<infer Ctx, infer ScopeContext, infer RunOptions, infer Deps, infer Out> ? [Ctx, ScopeContext, RunOptions, Deps, Out] : never;
-type InferComponentCtx<T> = InferComponentParams<T>[0];
-type InferComponentScopeContext<T> = InferComponentParams<T>[1];
-type InferComponentRunOptions<T> = InferComponentParams<T>[2];
-type InferComponentDeps<T> = InferComponentParams<T>[3];
-type InferComponentOut<T> = InferComponentParams<T>[4];
 declare function brandComponent<T extends object, Ctx, ScopeContext, RunOptions, Out>(obj: T): T & ComponentRef<Ctx, ScopeContext, RunOptions, Out>;
 declare function isComponent(value: unknown): value is Component<unknown, unknown, unknown, unknown, unknown>;
 //#endregion
@@ -39,12 +42,22 @@ type NoRunOptions = NonNullable<unknown>;
 type NoScopeContext = NonNullable<unknown>;
 type Middleware<AmbientContext, RunOptions = NoRunOptions, ScopeContext = NoScopeContext> = <T>(ctx: AmbientContext, options: Partial<RunOptions>, next: (ctx: AmbientContext & ScopeContext) => Promise<T> | T) => Promise<T> | T;
 //#endregion
-//#region src/runtime/explain.d.ts
+//#region src/explain/index.d.ts
 type ExplainResult = {
   name: string | undefined;
+  kind?: string;
+  tags?: string[];
   deps?: Record<string, ExplainResult>;
 };
 //#endregion
+//#region src/lazy.d.ts
+type Lazy<T> = () => T;
+declare const Lazy: {
+  cached<T>(factory: () => T): Lazy<T>;
+  and<S, T>(l: Lazy<S>, r: Lazy<T>): Lazy<S & T>;
+  map<S, T>(l: Lazy<S>, fn: (v: S) => T): Lazy<T>;
+};
+//#endregion
 //#region src/runtime/runtime.d.ts
 type SafeIntersect<A, B> = A extends undefined ? B : A & B;
 type OptionalArg<A> = A extends undefined ? [] : [A];
@@ -52,19 +65,18 @@ declare class Runtime<Ctx, ActualContext extends Ctx, ScopeContext, RunOptions,
   private readonly middleware;
   private readonly ctx;
   private readonly resolveFn;
-  constructor(middleware: Middleware<Ctx, RunOptions, ScopeContext>, ctx: ActualContext);
+  constructor(middleware: Middleware<Ctx, RunOptions, ScopeContext>, ctx: Lazy<ActualContext>);
   provide<Extension>(ext: Extension): Runtime<Ctx, ActualContext & Extension, ScopeContext, RunOptions, Requirements>;
+  provideLazy<Extension>(ext: () => Extension): Runtime<Ctx, ActualContext & Extension, ScopeContext, RunOptions, Requirements>;
   require<Extension>(): Runtime<Ctx, ActualContext, ScopeContext, RunOptions, SafeIntersect<Requirements, Extension>>;
   resolve: <Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, ...requirements: OptionalArg<Requirements>) => Out | Promise<Out>;
-  get component(): <Deps, F extends ComponentFactory<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>>(factory: F, deps?: { [T in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[T]> } | undefined, opts?: {
-    name?: string | undefined;
-  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>;
-  get classComponent(): <Deps, Ctor extends new (deps: Run<SafeIntersect<Requirements, ActualContext> & Deps, ScopeContext, RunOptions>) => InstanceType<Ctor>>(ctor: Ctor, deps?: { [K in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[K]> } | undefined, opts?: {
-    name?: string | undefined;
-  } | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, InstanceType<Ctor>>;
-  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "native"): ExplainResult;
-  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "ascii"): string;
-  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "mermaid"): string;
+  get component(): <Deps, F extends ComponentFactory<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>>(factory: F, deps?: { [T in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[T]> } | undefined, meta?: ComponentMeta | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, ReturnType<F>>;
+  get classComponent(): <Deps, Ctor extends (new (deps: Run<SafeIntersect<Requirements, ActualContext> & Deps, ScopeContext, RunOptions>) => InstanceType<Ctor>) & {
+    meta?: ComponentMeta | undefined;
+  }>(ctor: Ctor, deps?: { [K in keyof Deps]: ComponentInput<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps[K]> } | undefined, meta?: ComponentMeta | undefined) => Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, InstanceType<Ctor>>;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "native", showMeta?: boolean): ExplainResult;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "ascii", showMeta?: boolean): string;
+  explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>, format: "mermaid", showMeta?: boolean): string;
   explain<Deps, Out>(component: Component<SafeIntersect<Requirements, ActualContext>, ScopeContext, RunOptions, Deps, Out>): ExplainResult;
 }
 //#endregion
@@ -74,10 +86,36 @@ declare class RuntimeBuilder<AmbientContext, ScopeContext = unknown, Options = u
   constructor(middlewares?: Middleware<AmbientContext, Options, ScopeContext>[]);
   use<A, S, H>(mw: Middleware<A, H, S>): RuntimeBuilder<AmbientContext & A, ScopeContext & S, Options & H>;
   provide<ActualCtx extends AmbientContext>(ctx: ActualCtx): Runtime<AmbientContext, ActualCtx, ScopeContext, Options, undefined>;
+  provideLazy<ActualCtx extends AmbientContext>(ctx: () => ActualCtx): Runtime<AmbientContext, ActualCtx, ScopeContext, Options, undefined>;
   private buildMiddleware;
 }
 //#endregion
 //#region src/runtime/index.d.ts
 declare function buildRuntime(): RuntimeBuilder<Record<string, unknown>, unknown>;
 //#endregion
-export { Component, ComponentDefinition, ComponentFactory, ComponentInput, ComponentRef, InferComponentCtx, InferComponentDeps, InferComponentOut, InferComponentParams, InferComponentRunOptions, InferComponentScopeContext, Middleware, NoDeps, NoRunOptions, NoScopeContext, Run, brandComponent, buildRuntime, isComponent };
+//#region src/semantic/callable.d.ts
+type Callable<Ctx, ScopeContext, Args extends unknown[], Result, RunOptions> = ComponentFactory<Ctx, ScopeContext, RunOptions, unknown, (...args: Args) => Promise<Result>>;
+declare function callable<Ctx, Args extends unknown[], Result, RunOptions = NoRunOptions, ScopeContext = NoScopeContext>(options: RunOptions & ComponentMeta, fn: (app: Run<Ctx, ScopeContext, RunOptions>) => (...args: Args) => Promise<Result>): Callable<Ctx, ScopeContext, Args, Result, RunOptions>;
+type InferCallable<T> = T extends Callable<infer _Ctx, infer _ScopeContext, infer Args, infer Result, infer _RunOptions> ? (...args: Args) => Promise<Result> : never;
+//#endregion
+//#region src/semantic/client.d.ts
+type Client<Ctx, ScopeContext, Out, RunOptions> = ComponentFactory<Ctx, ScopeContext, RunOptions, unknown, Out>;
+declare function client<Ctx, Out, RunOptions = NoRunOptions, ScopeContext = NoScopeContext>(options: Omit<ComponentMeta, "kind">, fn: (app: Run<Ctx, ScopeContext, RunOptions>) => Out): Client<Ctx, ScopeContext, Out, RunOptions>;
+type InferClient<T> = T extends Client<infer _Ctx, infer _ScopeContext, infer Out, infer _RunOptions> ? Out : never;
+//#endregion
+//#region src/semantic/repo.d.ts
+type Repo<Ctx, ScopeContext, Out, RunOptions> = ComponentFactory<Ctx, ScopeContext, RunOptions, unknown, Out>;
+declare function repo<Ctx, Out, RunOptions = NoRunOptions, ScopeContext = NoScopeContext>(options: Omit<ComponentMeta, "kind">, fn: (app: Run<Ctx, ScopeContext, RunOptions>) => Out): Repo<Ctx, ScopeContext, Out, RunOptions>;
+type InferRepo<T> = T extends Repo<infer _Ctx, infer _ScopeContext, infer Out, infer _RunOptions> ? Out : never;
+//#endregion
+//#region src/semantic/service.d.ts
+type Service<Ctx, ScopeContext, Out, RunOptions> = ComponentFactory<Ctx, ScopeContext, RunOptions, unknown, Out>;
+declare function service<Ctx, Out, RunOptions = NoRunOptions, ScopeContext = NoScopeContext>(options: Omit<ComponentMeta, "kind"> | undefined, fn: (app: Run<Ctx, ScopeContext, RunOptions>) => Out): Service<Ctx, ScopeContext, Out, RunOptions>;
+type InferService<T> = T extends Service<infer _Ctx, infer _ScopeContext, infer Out, infer _RunOptions> ? Out : never;
+//#endregion
+//#region src/semantic/usecase.d.ts
+type Usecase<Ctx, ScopeContext, Args extends unknown[], Result, RunOptions> = Callable<Ctx, ScopeContext, Args, Result, RunOptions>;
+declare function usecase<Ctx, Args extends unknown[], Result, RunOptions = NoRunOptions, ScopeContext = NoScopeContext>(options: RunOptions & Omit<ComponentMeta, "kind">, fn: (app: Run<Ctx, ScopeContext, RunOptions>) => (...args: Args) => Promise<Result>): Usecase<Ctx, ScopeContext, Args, Result, RunOptions>;
+type InferUsecase<T> = InferCallable<T>;
+//#endregion
+export { Callable, Client, Component, ComponentDefinition, ComponentFactory, ComponentFactoryFn, ComponentInput, ComponentKind, ComponentMeta, ComponentRef, InferCallable, InferClient, InferRepo, InferService, InferUsecase, Middleware, NoDeps, NoRunOptions, NoScopeContext, Repo, Run, Service, Usecase, brandComponent, buildRuntime, callable, client, isComponent, repo, service, usecase };

package/dist/index.mjs

@@ -13,31 +13,115 @@ function isComponent(value) {
 	return typeof value === "object" && value !== null && value[COMPONENT] === true;
 }
 //#endregion
+//#region src/lazy.ts
+const Lazy = {
+	cached(factory) {
+		let cached;
+		return () => {
+			if (cached === void 0) cached = factory();
+			return cached;
+		};
+	},
+	and(l, r) {
+		return () => ({
+			...l(),
+			...r()
+		});
+	},
+	map(l, fn) {
+		return () => fn(l());
+	}
+};
+//#endregion
 //#region src/component/class-component.ts
 function defineClassComponent() {
-	return (ctor, deps, opts) => {
+	return (ctor, deps, meta) => {
 		const factory = (ctx) => {
 			return new ctor(ctx);
 		};
 		return brandComponent({
 			factory,
 			deps,
-			name: opts?.name ?? ctor.name
+			meta: {
+				name: (meta?.name ?? ctor.meta?.name) || void 0,
+				tags: (meta?.tags ?? ctor.meta?.tags) || void 0,
+				kind: (meta?.kind ?? ctor.meta?.kind) || void 0
+			}
 		});
 	};
 }
 //#endregion
 //#region src/component/functional-component.ts
 function defineFunctionalComponent() {
-	return (factory, deps, opts) => {
+	return (factory, deps, meta) => {
 		return brandComponent({
 			factory,
 			deps,
-			name: opts?.name
+			meta: {
+				name: (meta?.name ?? factory.meta?.name) || void 0,
+				tags: (meta?.tags ?? factory.meta?.tags) || void 0,
+				kind: (meta?.kind ?? factory.meta?.kind) || void 0
+			}
 		});
 	};
 }
 //#endregion
+//#region src/explain/index.ts
+const explain = (c) => {
+	const deps = {};
+	for (const [key, comp] of Object.entries(c.deps ?? {})) deps[key] = explain(comp);
+	return {
+		name: c.meta?.name,
+		kind: c.meta?.kind,
+		tags: c.meta?.tags,
+		deps
+	};
+};
+//#endregion
+//#region src/explain/ascii.ts
+const formatExplainLabel = (node, showMeta, edgeLabel) => {
+	let label = edgeLabel ?? node.name ?? "unnamed";
+	if (edgeLabel && showMeta && node.name) label += ` -> ${node.name}`;
+	if (showMeta && node.kind) label += ` [${node.kind}]`;
+	if (showMeta && node.tags?.length) label += ` {${node.tags.join(", ")}}`;
+	return label;
+};
+const toAsciiTree = (result, prefix = "", isLast = true, showMeta = false, edgeLabel) => {
+	const line = `${prefix}${isLast ? "└── " : "├── "}${formatExplainLabel(result, showMeta, edgeLabel)}`;
+	const deps = Object.entries(result.deps ?? {});
+	if (deps.length === 0) return line;
+	const childPrefix = prefix + (isLast ? "    " : "│   ");
+	return [line, ...deps.map(([key, dep], index) => toAsciiTree(dep, childPrefix, index === deps.length - 1, showMeta, key))].join("\n");
+};
+//#endregion
+//#region src/explain/mermaid.ts
+const sanitizeMermaidId = (value) => value.replace(/[^a-zA-Z0-9_]/g, "_");
+const escapeMermaidLabel = (value) => value.replace(/"/g, "\\\"");
+const formatMermaidLabel = (node, showMeta, fallbackName) => {
+	let label = node.name ?? fallbackName;
+	if (showMeta) {
+		const metaParts = [];
+		if (node.kind) metaParts.push(node.kind);
+		if (node.tags?.length) metaParts.push(node.tags.join(", "));
+		if (metaParts.length > 0) label += `<br/>[${metaParts.join(" | ")}]`;
+	}
+	return escapeMermaidLabel(label);
+};
+const collectMermaidLines = (node, nodeId, showMeta, fallbackName) => {
+	const lines = [];
+	lines.push(`    ${nodeId}["${formatMermaidLabel(node, showMeta, fallbackName)}"]`);
+	Object.entries(node.deps ?? {}).forEach(([key, dep], index) => {
+		const childId = sanitizeMermaidId(`${nodeId}__${key}__${dep.name ?? key ?? `node_${index}`}`);
+		lines.push(`    ${nodeId} -->|${escapeMermaidLabel(key)}| ${childId}`);
+		lines.push(...collectMermaidLines(dep, childId, showMeta, key));
+	});
+	return lines;
+};
+const toMermaid = (result, showMeta = false) => {
+	const rootName = result.name ?? "root";
+	return ["graph TD", ...collectMermaidLines(result, sanitizeMermaidId(rootName), showMeta, rootName)].join("\n");
+};
+//#endregion
 //#region src/runtime/create-resolver.ts
 function createResolver(mw) {
 	return (root, ctx) => {
@@ -99,49 +183,6 @@ function createResolver(mw) {
 	};
 }
 //#endregion
-//#region src/runtime/explain.ts
-const explain = (c) => {
-	const deps = {};
-	for (const [key, comp] of Object.entries(c.deps ?? {})) deps[key] = explain(comp);
-	return {
-		name: c.name,
-		deps
-	};
-};
-const toAsciiTree = (result, prefix = "", isLast = true) => {
-	const lines = [];
-	const connector = isLast ? "└── " : "├── ";
-	lines.push(prefix + connector + result.name);
-	const deps = Object.entries(result.deps ?? {});
-	const newPrefix = prefix + (isLast ? "    " : "│   ");
-	deps.forEach(([key, dep], index) => {
-		const isLastDep = index === deps.length - 1;
-		const connector = isLastDep ? "└── " : "├── ";
-		lines.push(`${newPrefix}${connector}[${key}]`);
-		const childLines = toAsciiTree(dep, newPrefix + (isLastDep ? "    " : "│   "), true).split("\n").slice(1);
-		lines.push(...childLines);
-	});
-	return lines.join("\n");
-};
-const toMermaid = (result, nodeId, isRoot = true) => {
-	const lines = [];
-	if (isRoot) {
-		lines.push("graph TD");
-		nodeId = result.name ?? "root";
-	}
-	const sanitizedId = nodeId.replace(/[^a-zA-Z0-9_]/g, "_");
-	if (isRoot) lines.push(`    ${sanitizedId}["${result.name}"]`);
-	Object.entries(result.deps ?? {}).forEach(([key, dep]) => {
-		const sanitizedDepId = (dep.name ? `${sanitizedId}_${dep.name}` : `${sanitizedId}_${key}`).replace(/[^a-zA-Z0-9_]/g, "_");
-		const displayName = dep.name ?? key;
-		lines.push(`    ${sanitizedDepId}["${displayName}"]`);
-		lines.push(`    ${sanitizedId} -->|${key}| ${sanitizedDepId}`);
-		const childLines = toMermaid(dep, sanitizedDepId, false).split("\n").slice(1);
-		lines.push(...childLines);
-	});
-	return lines.join("\n");
-};
-//#endregion
 //#region src/runtime/runtime.ts
 var Runtime = class Runtime {
 	resolveFn;
@@ -151,10 +192,10 @@ var Runtime = class Runtime {
 		this.resolveFn = createResolver(middleware);
 	}
 	provide(ext) {
-		return new Runtime(this.middleware, {
-			...this.ctx,
-			...ext
-		});
+		return new Runtime(this.middleware, Lazy.and(this.ctx, () => ext));
+	}
+	provideLazy(ext) {
+		return new Runtime(this.middleware, Lazy.and(this.ctx, Lazy.cached(ext)));
 	}
 	require() {
 		return new Runtime(this.middleware, this.ctx);
@@ -162,9 +203,9 @@ var Runtime = class Runtime {
 	resolve = (component, ...requirements) => {
 		const req = requirements[0];
 		const ctx = req ? {
-			...this.ctx,
+			...this.ctx(),
 			...req
-		} : { ...this.ctx };
+		} : { ...this.ctx() };
 		return this.resolveFn(component, ctx);
 	};
 	get component() {
@@ -173,11 +214,11 @@ var Runtime = class Runtime {
 	get classComponent() {
 		return defineClassComponent();
 	}
-	explain(component, format = "native") {
+	explain(component, format = "native", showMeta = false) {
 		const result = explain(component);
 		switch (format) {
-			case "ascii": return toAsciiTree(result);
-			case "mermaid": return toMermaid(result);
+			case "ascii": return toAsciiTree(result, "", true, showMeta);
+			case "mermaid": return toMermaid(result, showMeta);
 			case "native": return result;
 		}
 	}
@@ -193,7 +234,10 @@ var RuntimeBuilder = class RuntimeBuilder {
 		return new RuntimeBuilder([...this.middlewares, mw]);
 	}
 	provide(ctx) {
-		return new Runtime(this.buildMiddleware(), ctx);
+		return new Runtime(this.buildMiddleware(), () => ctx);
+	}
+	provideLazy(ctx) {
+		return new Runtime(this.buildMiddleware(), Lazy.cached(ctx));
 	}
 	buildMiddleware() {
 		const middlewares = this.middlewares;
@@ -216,4 +260,58 @@ function buildRuntime() {
 	return new RuntimeBuilder();
 }
 //#endregion
-export { brandComponent, buildRuntime, isComponent };
+//#region src/semantic/callable.ts
+function callable(options, fn) {
+	const factory = (ctx) => (...args) => {
+		return ctx.run(options, (inner) => fn(inner)(...args));
+	};
+	Object.assign(factory, { meta: {
+		kind: options.kind,
+		name: options.name,
+		tags: options.tags
+	} });
+	return factory;
+}
+//#endregion
+//#region src/semantic/client.ts
+function client(options, fn) {
+	const factory = fn;
+	Object.assign(factory, { meta: {
+		kind: "client",
+		name: options.name,
+		tags: options.tags
+	} });
+	return factory;
+}
+//#endregion
+//#region src/semantic/repo.ts
+function repo(options, fn) {
+	const factory = fn;
+	Object.assign(factory, { meta: {
+		kind: "repo",
+		name: options.name,
+		tags: options.tags
+	} });
+	return factory;
+}
+//#endregion
+//#region src/semantic/service.ts
+function service(options = {}, fn) {
+	const factory = fn;
+	Object.assign(factory, { meta: {
+		kind: "service",
+		name: options.name,
+		tags: options.tags
+	} });
+	return factory;
+}
+//#endregion
+//#region src/semantic/usecase.ts
+function usecase(options, fn) {
+	return callable({
+		kind: "usecase",
+		...options
+	}, fn);
+}
+//#endregion
+export { brandComponent, buildRuntime, callable, client, isComponent, repo, service, usecase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceteams/warp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Type-safe composition with execution scopes ",
   "type": "module",
   "files": [