@homeflare/alchemy 0.59.0 → 0.61.0

package/src/scope/guard.test.ts

@@ -1,128 +0,0 @@
-/**
- * `guardDuplicateIds` driven through a REAL `Alchemy.Stack(...)` body with real `Resource()`
- * classes — the same shape `litellm/fake-stack.ts` and `github/repo-apply-order-fake-stack.ts`
- * use for the same reason their own headers give: a check built only against this module's own
- * logic (duplicate-id.test.ts) proves the registry works, not that wiring it onto a resource
- * class via a `Proxy` actually intercepts the call Alchemy itself makes when a stack body
- * `yield*`s it.
- *
- * ⚠️ `dup-experiment.ts` (this PR's own throwaway script, not checked in) first measured the
- *   UNGUARDED failure mode this guards against: two different `Resource()` classes sharing a
- *   logical id compile a stack whose only entry at that fqn is the FIRST type, with no trace the
- *   second one ever ran. These tests are the regression guard for exactly that, once wrapped.
- */
-import { describe, expect, test } from 'bun:test';
-import * as Alchemy from 'alchemy';
-import { push as pushNamespace } from 'alchemy/Namespace';
-import type { Resource, ResourceLike } from 'alchemy/Resource';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import { guardDuplicateIds } from './guard.ts';
-
-interface Props {
-  readonly value: number;
-}
-interface TestResource extends Resource<string, Props, object> {}
-
-/** A plain `Resource()` class, wrapped, for a given vendor-style type string. */
-const guarded = (type: string) => guardDuplicateIds(Alchemy.Resource<TestResource>(type));
-
-type StackBody = Effect.Effect<unknown, unknown, unknown>;
-
-/** Same cast-at-the-typed-boundary shape as `litellm/fake-stack.ts`; see that file's own header. */
-const runStack = (body: StackBody) => {
-  const state = Alchemy.inMemoryState();
-  const stack = Alchemy.Stack as unknown as (
-    stackName: string,
-    options: { providers: Layer.Layer<never>; state: typeof state },
-    body: StackBody,
-  ) => Effect.Effect<
-    { readonly resources: Readonly<Record<string, ResourceLike>> },
-    unknown,
-    never
-  >;
-  return Effect.runPromiseExit(
-    stack('GuardTestStack', { providers: Layer.empty, state }, body).pipe(
-      Effect.provideService(Alchemy.Stage, 'test'),
-      Effect.scoped,
-    ),
-  );
-};
-
-describe('guardDuplicateIds, through a real stack', () => {
-  test('distinct ids both register', async () => {
-    const A = guarded('Test.A');
-    const B = guarded('Test.B');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* A('one', { value: 1 });
-        yield* B('two', { value: 2 });
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-    if (exit._tag !== 'Success') return;
-    expect(Object.keys(exit.value.resources).sort()).toEqual(['one', 'two']);
-  });
-
-  test('the same guarded type re-registering its own id stays a noop, not a death', async () => {
-    const A = guarded('Test.A');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* A('shared', { value: 1 });
-        yield* A('shared', { value: 1 });
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-  });
-
-  test('two different guarded types sharing an id die naming both, before either resource "wins"', async () => {
-    const Retirement = guarded('Nix.JobRetirement');
-    const Caddy = guarded('Caddy.Config');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Retirement('caddy', { value: 1 });
-        yield* Caddy('caddy', { value: 2 });
-      }),
-    );
-    expect(exit._tag).toBe('Failure');
-    if (exit._tag !== 'Failure') return;
-    const reasons = (exit.cause as { reasons: readonly { _tag: string; defect?: unknown }[] })
-      .reasons;
-    const reason = reasons[0];
-    expect(reason === undefined ? undefined : reason._tag).toBe('Die');
-    const defect = reason === undefined ? undefined : (reason.defect as Error | undefined);
-    expect(defect === undefined ? '' : String(defect.message)).toContain(
-      'REFUSING: duplicate resource id "caddy" in scope (root): ' +
-        'first declared by Nix.JobRetirement, again by Caddy.Config',
-    );
-  });
-
-  test('one guarded, one unguarded type sharing an id still dies (the guarded side still claims it)', async () => {
-    const Guarded = guarded('Test.Guarded');
-    const Unguarded = Alchemy.Resource<TestResource>('Test.Unguarded');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Guarded('shared', { value: 1 });
-        yield* Unguarded('shared', { value: 2 });
-      }),
-    );
-    // The unguarded side never calls `claimResourceId`, so Alchemy's own idempotent-registration
-    // branch runs instead (Resource.ts) and this SUCCEEDS as a silent noop — exactly the gap this
-    // PR documents as out of scope for a kit-only fix (docs/duplicate-resource-id.md). Asserting
-    // the current behaviour, not endorsing it: `guardDuplicateIds` only protects pairs where BOTH
-    // sides are wrapped.
-    expect(exit._tag).toBe('Success');
-  });
-
-  test('the same id in a nested namespace is a different scope', async () => {
-    const Retirement = guarded('Nix.JobRetirement');
-    const Caddy = guarded('Caddy.Config');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Retirement('caddy', { value: 1 });
-        yield* pushNamespace('child', Caddy('caddy', { value: 2 }));
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-  });
-});

package/src/scope/guard.ts

@@ -1,49 +0,0 @@
-/**
- * `guardDuplicateIds` — wrap a Resource class so every `("id", props)` call it makes first
- * claims that id through `duplicate-id.ts`'s per-stack registry, naming both resource types if
- * a second, different-typed resource already claimed it. See duplicate-id.ts's header for why
- * the check has to live HERE (at the moment of registration) rather than after the stack body
- * has finished running.
- *
- * Usage, in a resource's own file, right where it's exported today:
- *
- * ```ts
- * export const CaddyConfig = guardDuplicateIds(Resource<CaddyConfig>('Caddy.Config', { … }));
- * ```
- *
- * ★ A `Proxy` around the REAL class, not a reimplementation. `Resource()`'s return value is a
- *   callable object wearing an `Effectable.Prototype` (`Effect.isEffect(MyResource) === true`,
- *   for the bare-tag platform-resource pattern) plus `.ref`, `.Type`, `.Provider`, `.Self`,
- *   `.Aliases` — reconstructing that shape risks silently dropping one of them. A `Proxy` whose
- *   `get` trap is the default (`Reflect.get`) forwards every property read untouched; only the
- *   `apply` trap — the `MyResource("id", props)` call form — is new behaviour.
- * ⚠️ THE "REGISTER METHODS" OVERLOAD IS DELIBERATELY LEFT ALONE. `ResourceClass` is also callable
- *   with a single object argument to attach methods (`Resource()`'s own `typeof args[0] ===
- *   'object' ? Object.assign(...) : constructor(...)` branch) — that call mutates and returns the
- *   SAME class, carries no logical id, and has nothing to claim. Only a string first argument
- *   (the `(id, props)` form) goes through `claimResourceId`.
- */
-import type { ResourceClass, ResourceLike } from 'alchemy/Resource';
-import * as Effect from 'effect/Effect';
-import { claimResourceId } from './duplicate-id.ts';
-
-export const guardDuplicateIds = <R extends ResourceLike>(
-  resourceClass: ResourceClass<R>,
-): ResourceClass<R> =>
-  new Proxy(resourceClass, {
-    apply(target, thisArg, args: unknown[]) {
-      const id = args[0];
-      if (typeof id !== 'string') {
-        // The "attach methods" overload — not a registration, nothing to claim.
-        return Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);
-      }
-      return Effect.gen(function* () {
-        yield* claimResourceId(resourceClass.Type, id);
-        return yield* Reflect.apply(
-          target as (...a: unknown[]) => unknown,
-          thisArg,
-          args,
-        ) as Effect.Effect<R>;
-      });
-    },
-  }) as ResourceClass<R>;