@soda-gql/common 0.0.8 → 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# @soda-gql/common
+
+[![npm version](https://img.shields.io/npm/v/@soda-gql/common.svg)](https://www.npmjs.com/package/@soda-gql/common)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Shared utilities and types for the soda-gql ecosystem.
+
+## Installation
+
+```bash
+bun add @soda-gql/common
+```
+
+> **Note**: This package is primarily used internally by other soda-gql packages. Direct usage is only needed for advanced integration scenarios.
+
+## Overview
+
+This package provides shared utilities used across the soda-gql ecosystem:
+
+- Portable utilities for cross-environment compatibility
+- Canonical ID generation and parsing
+- Path building utilities
+- Zod validation helpers
+
+## Exports
+
+### Main Entry (`@soda-gql/common`)
+
+Common types and utilities:
+
+```typescript
+import { ... } from "@soda-gql/common";
+```
+
+### Portable (`@soda-gql/common/portable`)
+
+Cross-environment utilities:
+
+```typescript
+import { ... } from "@soda-gql/common/portable";
+```
+
+### Canonical ID (`@soda-gql/common/canonical-id`)
+
+Canonical ID generation and parsing:
+
+```typescript
+import { createCanonicalId, parseCanonicalId } from "@soda-gql/common/canonical-id";
+
+// Create a canonical ID
+const id = createCanonicalId("/path/to/file.ts", "userQuery");
+// Result: "/path/to/file.ts::userQuery"
+
+// Parse a canonical ID
+const parsed = parseCanonicalId(id);
+// Result: { filePath: "/path/to/file.ts", astPath: "userQuery" }
+```
+
+### Utils (`@soda-gql/common/utils`)
+
+General utility functions:
+
+```typescript
+import { ... } from "@soda-gql/common/utils";
+```
+
+### Zod (`@soda-gql/common/zod`)
+
+Zod validation helpers:
+
+```typescript
+import { ... } from "@soda-gql/common/zod";
+```
+
+### Scheduler (Effect System)
+
+Generator-based effect system for scheduling sync and async operations:
+
+```typescript
+import {
+  createSyncScheduler,
+  createAsyncScheduler,
+  PureEffect,
+  DeferEffect,
+  ParallelEffect,
+  YieldEffect,
+} from "@soda-gql/common";
+
+// Sync usage
+const syncScheduler = createSyncScheduler();
+const result = syncScheduler.run(function* () {
+  const a = yield* new PureEffect(1).run();
+  const b = yield* new PureEffect(2).run();
+  return a + b;
+});
+
+// Async usage with parallel effects
+const asyncScheduler = createAsyncScheduler();
+const asyncResult = await asyncScheduler.run(function* () {
+  const data = yield* new DeferEffect(fetchData()).run();
+  yield* new YieldEffect().run(); // Yield to event loop
+  return processData(data);
+});
+```
+
+### Test Utilities (`@soda-gql/common/test`)
+
+Shared test utilities for soda-gql packages (internal use):
+
+```typescript
+import { createTempDir, TestSuite } from "@soda-gql/common/test";
+```
+
+## Related Packages
+
+- [@soda-gql/core](../core) - Core types and utilities
+- [@soda-gql/builder](../builder) - Static analysis engine
+
+## License
+
+MIT

package/dist/index.cjs

@@ -2,19 +2,282 @@ const require_canonical_id = require('./canonical-id-BFcryTw5.cjs');
 const require_utils = require('./utils-CmLf7LU5.cjs');
 const require_portable = require('./portable-C_7gJWmz.cjs');
 const require_zod = require('./zod-CynYgOoN.cjs');
+let neverthrow = require("neverthrow");
 
+//#region packages/common/src/scheduler/types.ts
+/**
+* Abstract base class for all effects.
+* Effects encapsulate both the data and the execution logic.
+*
+* @template TResult - The type of value this effect produces when executed
+*
+* @example
+* ```typescript
+* function* myGenerator() {
+*   const value = yield* new PureEffect(42).run();
+*   return value; // 42
+* }
+* ```
+*/
+var Effect = class {
+	/**
+	* Execute the effect synchronously and return the result.
+	*/
+	executeSync() {
+		return this._executeSync();
+	}
+	/**
+	* Execute the effect asynchronously and return the result.
+	*/
+	async executeAsync() {
+		return this._executeAsync();
+	}
+	/**
+	* Returns a generator that yields this effect and returns the result.
+	* Enables the `yield*` pattern for cleaner effect handling.
+	*
+	* @example
+	* ```typescript
+	* const value = yield* effect.run();
+	* ```
+	*/
+	*run() {
+		return EffectReturn.unwrap(yield this);
+	}
+};
+const EFFECT_RETURN = Symbol("EffectReturn");
+var EffectReturn = class EffectReturn {
+	[EFFECT_RETURN];
+	constructor(value) {
+		this[EFFECT_RETURN] = value;
+	}
+	static wrap(value) {
+		return new EffectReturn(value);
+	}
+	static unwrap(value) {
+		return value[EFFECT_RETURN];
+	}
+};
+/**
+* Create a SchedulerError.
+*/
+const createSchedulerError = (message, cause) => ({
+	kind: "scheduler-error",
+	message,
+	cause
+});
+
+//#endregion
+//#region packages/common/src/scheduler/async-scheduler.ts
+/**
+* Create an asynchronous scheduler.
+*
+* This scheduler can handle all effect types including defer and yield.
+* Parallel effects are executed concurrently using Promise.all.
+*
+* @returns An AsyncScheduler instance
+*
+* @example
+* const scheduler = createAsyncScheduler();
+* const result = await scheduler.run(function* () {
+*   const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+*   yield* new YieldEffect().run(); // Yield to event loop
+*   return data;
+* });
+*/
+const createAsyncScheduler = () => {
+	const run = async (generatorFn) => {
+		try {
+			const generator = generatorFn();
+			let result = generator.next();
+			while (!result.done) {
+				const effect = result.value;
+				const effectResult = await effect.executeAsync();
+				result = generator.next(EffectReturn.wrap(effectResult));
+			}
+			return (0, neverthrow.ok)(result.value);
+		} catch (error) {
+			if (isSchedulerError$1(error)) {
+				return (0, neverthrow.err)(error);
+			}
+			return (0, neverthrow.err)(createSchedulerError(error instanceof Error ? error.message : String(error), error));
+		}
+	};
+	return { run };
+};
+/**
+* Type guard for SchedulerError.
+*/
+const isSchedulerError$1 = (error) => {
+	return typeof error === "object" && error !== null && error.kind === "scheduler-error";
+};
+
+//#endregion
+//#region packages/common/src/scheduler/effect.ts
+/**
+* Pure effect - returns a value immediately.
+* Works in both sync and async schedulers.
+*
+* @example
+* const result = yield* new PureEffect(42).run(); // 42
+*/
+var PureEffect = class extends Effect {
+	constructor(pureValue) {
+		super();
+		this.pureValue = pureValue;
+	}
+	_executeSync() {
+		return this.pureValue;
+	}
+	_executeAsync() {
+		return Promise.resolve(this.pureValue);
+	}
+};
+/**
+* Defer effect - wraps a Promise for async execution.
+* Only works in async schedulers; throws in sync schedulers.
+*
+* @example
+* const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+*/
+var DeferEffect = class extends Effect {
+	constructor(promise) {
+		super();
+		this.promise = promise;
+	}
+	_executeSync() {
+		throw new Error("DeferEffect is not supported in sync scheduler. Use AsyncScheduler instead.");
+	}
+	_executeAsync() {
+		return this.promise;
+	}
+};
+/**
+* Parallel effect - executes multiple effects concurrently.
+* In sync schedulers, effects are executed sequentially.
+* In async schedulers, effects are executed with Promise.all.
+*
+* @example
+* const results = yield* new ParallelEffect([new PureEffect(1), new PureEffect(2)]).run(); // [1, 2]
+*/
+var ParallelEffect = class extends Effect {
+	constructor(effects) {
+		super();
+		this.effects = effects;
+	}
+	_executeSync() {
+		return this.effects.map((e) => e.executeSync());
+	}
+	async _executeAsync() {
+		return Promise.all(this.effects.map((e) => e.executeAsync()));
+	}
+};
+/**
+* Yield effect - yields control back to the event loop.
+* This helps prevent blocking the event loop in long-running operations.
+* Only works in async schedulers; throws in sync schedulers.
+*
+* @example
+* for (let i = 0; i < 10000; i++) {
+*   doWork(i);
+*   if (i % 100 === 0) {
+*     yield* new YieldEffect().run();
+*   }
+* }
+*/
+var YieldEffect = class extends Effect {
+	_executeSync() {
+		throw new Error("YieldEffect is not supported in sync scheduler. Use AsyncScheduler instead.");
+	}
+	async _executeAsync() {
+		await new Promise((resolve) => {
+			if (typeof setImmediate !== "undefined") {
+				setImmediate(resolve);
+			} else {
+				setTimeout(resolve, 0);
+			}
+		});
+	}
+};
+/**
+* Effect factory namespace for convenience.
+* Provides static methods to create effects.
+*/
+const Effects = {
+	pure: (value) => new PureEffect(value),
+	defer: (promise) => new DeferEffect(promise),
+	parallel: (effects) => new ParallelEffect(effects),
+	yield: () => new YieldEffect()
+};
+
+//#endregion
+//#region packages/common/src/scheduler/sync-scheduler.ts
+/**
+* Create a synchronous scheduler.
+*
+* This scheduler executes generators synchronously.
+* It throws an error if an async-only effect (defer, yield) is encountered.
+*
+* @returns A SyncScheduler instance
+*
+* @example
+* const scheduler = createSyncScheduler();
+* const result = scheduler.run(function* () {
+*   const a = yield* new PureEffect(1).run();
+*   const b = yield* new PureEffect(2).run();
+*   return a + b;
+* });
+* // result = ok(3)
+*/
+const createSyncScheduler = () => {
+	const run = (generatorFn) => {
+		try {
+			const generator = generatorFn();
+			let result = generator.next();
+			while (!result.done) {
+				const effect = result.value;
+				const effectResult = effect.executeSync();
+				result = generator.next(EffectReturn.wrap(effectResult));
+			}
+			return (0, neverthrow.ok)(result.value);
+		} catch (error) {
+			if (isSchedulerError(error)) {
+				return (0, neverthrow.err)(error);
+			}
+			return (0, neverthrow.err)(createSchedulerError(error instanceof Error ? error.message : String(error), error));
+		}
+	};
+	return { run };
+};
+/**
+* Type guard for SchedulerError.
+*/
+const isSchedulerError = (error) => {
+	return typeof error === "object" && error !== null && error.kind === "scheduler-error";
+};
+
+//#endregion
 exports.CanonicalIdSchema = require_canonical_id.CanonicalIdSchema;
+exports.DeferEffect = DeferEffect;
+exports.Effect = Effect;
+exports.Effects = Effects;
 exports.MODULE_EXTENSION_CANDIDATES = require_utils.MODULE_EXTENSION_CANDIDATES;
+exports.ParallelEffect = ParallelEffect;
+exports.PureEffect = PureEffect;
+exports.YieldEffect = YieldEffect;
 exports.__resetPortableFSForTests = require_portable.__resetPortableFSForTests;
 exports.__resetPortableHasherForTests = require_portable.__resetPortableHasherForTests;
 exports.buildAstPath = require_canonical_id.buildAstPath;
 exports.cachedFn = require_utils.cachedFn;
+exports.createAsyncScheduler = createAsyncScheduler;
 exports.createCanonicalId = require_canonical_id.createCanonicalId;
 exports.createCanonicalTracker = require_canonical_id.createCanonicalTracker;
 exports.createOccurrenceTracker = require_canonical_id.createOccurrenceTracker;
 exports.createPathTracker = require_canonical_id.createPathTracker;
 exports.createPortableFS = require_portable.createPortableFS;
 exports.createPortableHasher = require_portable.createPortableHasher;
+exports.createSchedulerError = createSchedulerError;
+exports.createSyncScheduler = createSyncScheduler;
 exports.defineSchemaFor = require_zod.defineSchemaFor;
 exports.generateId = require_portable.generateId;
 exports.getPortableFS = require_portable.getPortableFS;

package/dist/index.d.cts

@@ -2,4 +2,219 @@ import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as
 import { a as resetPortableForTests, c as HashAlgorithm, d as createPortableHasher, f as getPortableHasher, g as getPortableFS, h as createPortableFS, i as once, l as PortableHasher, m as __resetPortableFSForTests, n as SpawnResult, o as runtime, p as PortableFS, r as spawn, s as generateId, t as SpawnOptions, u as __resetPortableHasherForTests } from "./index-DaAp2rNj.cjs";
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./index-LaXfl_e_.cjs";
 import { n as ShapeFor, r as defineSchemaFor, t as SchemaFor } from "./index-LHYortIn.cjs";
-export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, PortableFS, PortableHasher, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+import { Result } from "neverthrow";
+
+//#region packages/common/src/scheduler/types.d.ts
+
+/**
+ * Abstract base class for all effects.
+ * Effects encapsulate both the data and the execution logic.
+ *
+ * @template TResult - The type of value this effect produces when executed
+ *
+ * @example
+ * ```typescript
+ * function* myGenerator() {
+ *   const value = yield* new PureEffect(42).run();
+ *   return value; // 42
+ * }
+ * ```
+ */
+declare abstract class Effect<TResult = unknown> {
+  /**
+   * Execute the effect synchronously and return the result.
+   */
+  executeSync(): TResult;
+  /**
+   * Execute the effect asynchronously and return the result.
+   */
+  executeAsync(): Promise<TResult>;
+  /**
+   * Returns a generator that yields this effect and returns the result.
+   * Enables the `yield*` pattern for cleaner effect handling.
+   *
+   * @example
+   * ```typescript
+   * const value = yield* effect.run();
+   * ```
+   */
+  run(): Generator<Effect<TResult>, TResult, EffectReturn>;
+  /**
+   * Internal synchronous execution logic.
+   * Subclasses must implement this method.
+   */
+  protected abstract _executeSync(): TResult;
+  /**
+   * Internal asynchronous execution logic.
+   * Subclasses must implement this method.
+   */
+  protected abstract _executeAsync(): Promise<TResult>;
+}
+declare const EFFECT_RETURN: unique symbol;
+declare class EffectReturn<TResult = unknown> {
+  private readonly [EFFECT_RETURN];
+  private constructor();
+  static wrap<TResult>(value: TResult): EffectReturn<TResult>;
+  static unwrap<TResult>(value: EffectReturn<TResult>): TResult;
+}
+/**
+ * Extract the result type from an Effect.
+ */
+type EffectResult<E> = E extends Effect<infer T> ? T : never;
+/**
+ * Generator type that yields Effects.
+ */
+type EffectGenerator<TReturn> = Generator<Effect, TReturn, EffectReturn>;
+/**
+ * Generator function type that creates an EffectGenerator.
+ */
+type EffectGeneratorFn<TReturn> = () => EffectGenerator<TReturn>;
+/**
+ * Error type for scheduler operations.
+ */
+type SchedulerError = {
+  readonly kind: "scheduler-error";
+  readonly message: string;
+  readonly cause?: unknown;
+};
+/**
+ * Create a SchedulerError.
+ */
+declare const createSchedulerError: (message: string, cause?: unknown) => SchedulerError;
+/**
+ * Synchronous scheduler interface.
+ * Throws if an async-only effect (defer, yield) is encountered.
+ */
+interface SyncScheduler {
+  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Result<TReturn, SchedulerError>;
+}
+/**
+ * Asynchronous scheduler interface.
+ * Handles all effect types including defer, yield, and parallel.
+ */
+interface AsyncScheduler {
+  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Promise<Result<TReturn, SchedulerError>>;
+}
+//#endregion
+//#region packages/common/src/scheduler/async-scheduler.d.ts
+/**
+ * Create an asynchronous scheduler.
+ *
+ * This scheduler can handle all effect types including defer and yield.
+ * Parallel effects are executed concurrently using Promise.all.
+ *
+ * @returns An AsyncScheduler instance
+ *
+ * @example
+ * const scheduler = createAsyncScheduler();
+ * const result = await scheduler.run(function* () {
+ *   const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+ *   yield* new YieldEffect().run(); // Yield to event loop
+ *   return data;
+ * });
+ */
+declare const createAsyncScheduler: () => AsyncScheduler;
+//#endregion
+//#region packages/common/src/scheduler/effect.d.ts
+/**
+ * Pure effect - returns a value immediately.
+ * Works in both sync and async schedulers.
+ *
+ * @example
+ * const result = yield* new PureEffect(42).run(); // 42
+ */
+declare class PureEffect<T> extends Effect<T> {
+  readonly pureValue: T;
+  constructor(pureValue: T);
+  protected _executeSync(): T;
+  protected _executeAsync(): Promise<T>;
+}
+/**
+ * Defer effect - wraps a Promise for async execution.
+ * Only works in async schedulers; throws in sync schedulers.
+ *
+ * @example
+ * const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+ */
+declare class DeferEffect<T> extends Effect<T> {
+  readonly promise: Promise<T>;
+  constructor(promise: Promise<T>);
+  protected _executeSync(): T;
+  protected _executeAsync(): Promise<T>;
+}
+/**
+ * Parallel effect - executes multiple effects concurrently.
+ * In sync schedulers, effects are executed sequentially.
+ * In async schedulers, effects are executed with Promise.all.
+ *
+ * @example
+ * const results = yield* new ParallelEffect([new PureEffect(1), new PureEffect(2)]).run(); // [1, 2]
+ */
+declare class ParallelEffect extends Effect<readonly unknown[]> {
+  readonly effects: readonly Effect<unknown>[];
+  constructor(effects: readonly Effect<unknown>[]);
+  protected _executeSync(): readonly unknown[];
+  protected _executeAsync(): Promise<readonly unknown[]>;
+}
+/**
+ * Yield effect - yields control back to the event loop.
+ * This helps prevent blocking the event loop in long-running operations.
+ * Only works in async schedulers; throws in sync schedulers.
+ *
+ * @example
+ * for (let i = 0; i < 10000; i++) {
+ *   doWork(i);
+ *   if (i % 100 === 0) {
+ *     yield* new YieldEffect().run();
+ *   }
+ * }
+ */
+declare class YieldEffect extends Effect<void> {
+  protected _executeSync(): void;
+  protected _executeAsync(): Promise<void>;
+}
+/**
+ * Effect factory namespace for convenience.
+ * Provides static methods to create effects.
+ */
+declare const Effects: {
+  /**
+   * Create a pure effect that returns a value immediately.
+   */
+  readonly pure: <T>(value: T) => PureEffect<T>;
+  /**
+   * Create a defer effect that wraps a Promise.
+   */
+  readonly defer: <T>(promise: Promise<T>) => DeferEffect<T>;
+  /**
+   * Create a parallel effect that executes multiple effects concurrently.
+   */
+  readonly parallel: (effects: readonly Effect<unknown>[]) => ParallelEffect;
+  /**
+   * Create a yield effect that returns control to the event loop.
+   */
+  readonly yield: () => YieldEffect;
+};
+//#endregion
+//#region packages/common/src/scheduler/sync-scheduler.d.ts
+/**
+ * Create a synchronous scheduler.
+ *
+ * This scheduler executes generators synchronously.
+ * It throws an error if an async-only effect (defer, yield) is encountered.
+ *
+ * @returns A SyncScheduler instance
+ *
+ * @example
+ * const scheduler = createSyncScheduler();
+ * const result = scheduler.run(function* () {
+ *   const a = yield* new PureEffect(1).run();
+ *   const b = yield* new PureEffect(2).run();
+ *   return a + b;
+ * });
+ * // result = ok(3)
+ */
+declare const createSyncScheduler: () => SyncScheduler;
+//#endregion
+export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/scheduler/types.ts","../src/scheduler/async-scheduler.ts","../src/scheduler/effect.ts","../src/scheduler/sync-scheduler.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.d.mts

@@ -2,4 +2,219 @@ import { a as createCanonicalTracker, c as CanonicalId, i as buildAstPath, l as
 import { a as resetPortableForTests, c as HashAlgorithm, d as createPortableHasher, f as getPortableHasher, g as getPortableFS, h as createPortableFS, i as once, l as PortableHasher, m as __resetPortableFSForTests, n as SpawnResult, o as runtime, p as PortableFS, r as spawn, s as generateId, t as SpawnOptions, u as __resetPortableHasherForTests } from "./index-BedBpKbv.mjs";
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./index-Dv8spPt0.mjs";
 import { n as ShapeFor, r as defineSchemaFor, t as SchemaFor } from "./index-Dit86qkX.mjs";
-export { CanonicalId, CanonicalIdSchema, CanonicalPathTracker, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, PortableFS, PortableHasher, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+import { Result } from "neverthrow";
+
+//#region packages/common/src/scheduler/types.d.ts
+
+/**
+ * Abstract base class for all effects.
+ * Effects encapsulate both the data and the execution logic.
+ *
+ * @template TResult - The type of value this effect produces when executed
+ *
+ * @example
+ * ```typescript
+ * function* myGenerator() {
+ *   const value = yield* new PureEffect(42).run();
+ *   return value; // 42
+ * }
+ * ```
+ */
+declare abstract class Effect<TResult = unknown> {
+  /**
+   * Execute the effect synchronously and return the result.
+   */
+  executeSync(): TResult;
+  /**
+   * Execute the effect asynchronously and return the result.
+   */
+  executeAsync(): Promise<TResult>;
+  /**
+   * Returns a generator that yields this effect and returns the result.
+   * Enables the `yield*` pattern for cleaner effect handling.
+   *
+   * @example
+   * ```typescript
+   * const value = yield* effect.run();
+   * ```
+   */
+  run(): Generator<Effect<TResult>, TResult, EffectReturn>;
+  /**
+   * Internal synchronous execution logic.
+   * Subclasses must implement this method.
+   */
+  protected abstract _executeSync(): TResult;
+  /**
+   * Internal asynchronous execution logic.
+   * Subclasses must implement this method.
+   */
+  protected abstract _executeAsync(): Promise<TResult>;
+}
+declare const EFFECT_RETURN: unique symbol;
+declare class EffectReturn<TResult = unknown> {
+  private readonly [EFFECT_RETURN];
+  private constructor();
+  static wrap<TResult>(value: TResult): EffectReturn<TResult>;
+  static unwrap<TResult>(value: EffectReturn<TResult>): TResult;
+}
+/**
+ * Extract the result type from an Effect.
+ */
+type EffectResult<E> = E extends Effect<infer T> ? T : never;
+/**
+ * Generator type that yields Effects.
+ */
+type EffectGenerator<TReturn> = Generator<Effect, TReturn, EffectReturn>;
+/**
+ * Generator function type that creates an EffectGenerator.
+ */
+type EffectGeneratorFn<TReturn> = () => EffectGenerator<TReturn>;
+/**
+ * Error type for scheduler operations.
+ */
+type SchedulerError = {
+  readonly kind: "scheduler-error";
+  readonly message: string;
+  readonly cause?: unknown;
+};
+/**
+ * Create a SchedulerError.
+ */
+declare const createSchedulerError: (message: string, cause?: unknown) => SchedulerError;
+/**
+ * Synchronous scheduler interface.
+ * Throws if an async-only effect (defer, yield) is encountered.
+ */
+interface SyncScheduler {
+  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Result<TReturn, SchedulerError>;
+}
+/**
+ * Asynchronous scheduler interface.
+ * Handles all effect types including defer, yield, and parallel.
+ */
+interface AsyncScheduler {
+  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Promise<Result<TReturn, SchedulerError>>;
+}
+//#endregion
+//#region packages/common/src/scheduler/async-scheduler.d.ts
+/**
+ * Create an asynchronous scheduler.
+ *
+ * This scheduler can handle all effect types including defer and yield.
+ * Parallel effects are executed concurrently using Promise.all.
+ *
+ * @returns An AsyncScheduler instance
+ *
+ * @example
+ * const scheduler = createAsyncScheduler();
+ * const result = await scheduler.run(function* () {
+ *   const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+ *   yield* new YieldEffect().run(); // Yield to event loop
+ *   return data;
+ * });
+ */
+declare const createAsyncScheduler: () => AsyncScheduler;
+//#endregion
+//#region packages/common/src/scheduler/effect.d.ts
+/**
+ * Pure effect - returns a value immediately.
+ * Works in both sync and async schedulers.
+ *
+ * @example
+ * const result = yield* new PureEffect(42).run(); // 42
+ */
+declare class PureEffect<T> extends Effect<T> {
+  readonly pureValue: T;
+  constructor(pureValue: T);
+  protected _executeSync(): T;
+  protected _executeAsync(): Promise<T>;
+}
+/**
+ * Defer effect - wraps a Promise for async execution.
+ * Only works in async schedulers; throws in sync schedulers.
+ *
+ * @example
+ * const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+ */
+declare class DeferEffect<T> extends Effect<T> {
+  readonly promise: Promise<T>;
+  constructor(promise: Promise<T>);
+  protected _executeSync(): T;
+  protected _executeAsync(): Promise<T>;
+}
+/**
+ * Parallel effect - executes multiple effects concurrently.
+ * In sync schedulers, effects are executed sequentially.
+ * In async schedulers, effects are executed with Promise.all.
+ *
+ * @example
+ * const results = yield* new ParallelEffect([new PureEffect(1), new PureEffect(2)]).run(); // [1, 2]
+ */
+declare class ParallelEffect extends Effect<readonly unknown[]> {
+  readonly effects: readonly Effect<unknown>[];
+  constructor(effects: readonly Effect<unknown>[]);
+  protected _executeSync(): readonly unknown[];
+  protected _executeAsync(): Promise<readonly unknown[]>;
+}
+/**
+ * Yield effect - yields control back to the event loop.
+ * This helps prevent blocking the event loop in long-running operations.
+ * Only works in async schedulers; throws in sync schedulers.
+ *
+ * @example
+ * for (let i = 0; i < 10000; i++) {
+ *   doWork(i);
+ *   if (i % 100 === 0) {
+ *     yield* new YieldEffect().run();
+ *   }
+ * }
+ */
+declare class YieldEffect extends Effect<void> {
+  protected _executeSync(): void;
+  protected _executeAsync(): Promise<void>;
+}
+/**
+ * Effect factory namespace for convenience.
+ * Provides static methods to create effects.
+ */
+declare const Effects: {
+  /**
+   * Create a pure effect that returns a value immediately.
+   */
+  readonly pure: <T>(value: T) => PureEffect<T>;
+  /**
+   * Create a defer effect that wraps a Promise.
+   */
+  readonly defer: <T>(promise: Promise<T>) => DeferEffect<T>;
+  /**
+   * Create a parallel effect that executes multiple effects concurrently.
+   */
+  readonly parallel: (effects: readonly Effect<unknown>[]) => ParallelEffect;
+  /**
+   * Create a yield effect that returns control to the event loop.
+   */
+  readonly yield: () => YieldEffect;
+};
+//#endregion
+//#region packages/common/src/scheduler/sync-scheduler.d.ts
+/**
+ * Create a synchronous scheduler.
+ *
+ * This scheduler executes generators synchronously.
+ * It throws an error if an async-only effect (defer, yield) is encountered.
+ *
+ * @returns A SyncScheduler instance
+ *
+ * @example
+ * const scheduler = createSyncScheduler();
+ * const result = scheduler.run(function* () {
+ *   const a = yield* new PureEffect(1).run();
+ *   const b = yield* new PureEffect(2).run();
+ *   return a + b;
+ * });
+ * // result = ok(3)
+ */
+declare const createSyncScheduler: () => SyncScheduler;
+//#endregion
+export { type AsyncScheduler, CanonicalId, CanonicalIdSchema, CanonicalPathTracker, DeferEffect, Effect, type EffectGenerator, type EffectGeneratorFn, type EffectResult, Effects, HashAlgorithm, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PortableFS, PortableHasher, PureEffect, type SchedulerError, SchemaFor, ScopeFrame, ScopeHandle, ShapeFor, SpawnOptions, SpawnResult, type SyncScheduler, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/scheduler/types.ts","../src/scheduler/async-scheduler.ts","../src/scheduler/effect.ts","../src/scheduler/sync-scheduler.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.mjs

@@ -2,5 +2,260 @@ import { a as getPortableHasher, c as getPortableFS, d as runtime, i as createPo
 import { a as resolveRelativeImportWithExistenceCheck, i as normalizePath, n as isExternalSpecifier, o as resolveRelativeImportWithReferences, r as isRelativeSpecifier, s as cachedFn, t as MODULE_EXTENSION_CANDIDATES } from "./utils-DLEgAn7q.mjs";
 import { a as CanonicalIdSchema, i as createPathTracker, n as createCanonicalTracker, o as createCanonicalId, r as createOccurrenceTracker, t as buildAstPath } from "./canonical-id-BFnyQGST.mjs";
 import { t as defineSchemaFor } from "./zod-DeSimXdI.mjs";
+import { err, ok } from "neverthrow";
 
-export { CanonicalIdSchema, MODULE_EXTENSION_CANDIDATES, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+//#region packages/common/src/scheduler/types.ts
+/**
+* Abstract base class for all effects.
+* Effects encapsulate both the data and the execution logic.
+*
+* @template TResult - The type of value this effect produces when executed
+*
+* @example
+* ```typescript
+* function* myGenerator() {
+*   const value = yield* new PureEffect(42).run();
+*   return value; // 42
+* }
+* ```
+*/
+var Effect = class {
+	/**
+	* Execute the effect synchronously and return the result.
+	*/
+	executeSync() {
+		return this._executeSync();
+	}
+	/**
+	* Execute the effect asynchronously and return the result.
+	*/
+	async executeAsync() {
+		return this._executeAsync();
+	}
+	/**
+	* Returns a generator that yields this effect and returns the result.
+	* Enables the `yield*` pattern for cleaner effect handling.
+	*
+	* @example
+	* ```typescript
+	* const value = yield* effect.run();
+	* ```
+	*/
+	*run() {
+		return EffectReturn.unwrap(yield this);
+	}
+};
+const EFFECT_RETURN = Symbol("EffectReturn");
+var EffectReturn = class EffectReturn {
+	[EFFECT_RETURN];
+	constructor(value) {
+		this[EFFECT_RETURN] = value;
+	}
+	static wrap(value) {
+		return new EffectReturn(value);
+	}
+	static unwrap(value) {
+		return value[EFFECT_RETURN];
+	}
+};
+/**
+* Create a SchedulerError.
+*/
+const createSchedulerError = (message, cause) => ({
+	kind: "scheduler-error",
+	message,
+	cause
+});
+
+//#endregion
+//#region packages/common/src/scheduler/async-scheduler.ts
+/**
+* Create an asynchronous scheduler.
+*
+* This scheduler can handle all effect types including defer and yield.
+* Parallel effects are executed concurrently using Promise.all.
+*
+* @returns An AsyncScheduler instance
+*
+* @example
+* const scheduler = createAsyncScheduler();
+* const result = await scheduler.run(function* () {
+*   const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+*   yield* new YieldEffect().run(); // Yield to event loop
+*   return data;
+* });
+*/
+const createAsyncScheduler = () => {
+	const run = async (generatorFn) => {
+		try {
+			const generator = generatorFn();
+			let result = generator.next();
+			while (!result.done) {
+				const effect = result.value;
+				const effectResult = await effect.executeAsync();
+				result = generator.next(EffectReturn.wrap(effectResult));
+			}
+			return ok(result.value);
+		} catch (error) {
+			if (isSchedulerError$1(error)) {
+				return err(error);
+			}
+			return err(createSchedulerError(error instanceof Error ? error.message : String(error), error));
+		}
+	};
+	return { run };
+};
+/**
+* Type guard for SchedulerError.
+*/
+const isSchedulerError$1 = (error) => {
+	return typeof error === "object" && error !== null && error.kind === "scheduler-error";
+};
+
+//#endregion
+//#region packages/common/src/scheduler/effect.ts
+/**
+* Pure effect - returns a value immediately.
+* Works in both sync and async schedulers.
+*
+* @example
+* const result = yield* new PureEffect(42).run(); // 42
+*/
+var PureEffect = class extends Effect {
+	constructor(pureValue) {
+		super();
+		this.pureValue = pureValue;
+	}
+	_executeSync() {
+		return this.pureValue;
+	}
+	_executeAsync() {
+		return Promise.resolve(this.pureValue);
+	}
+};
+/**
+* Defer effect - wraps a Promise for async execution.
+* Only works in async schedulers; throws in sync schedulers.
+*
+* @example
+* const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();
+*/
+var DeferEffect = class extends Effect {
+	constructor(promise) {
+		super();
+		this.promise = promise;
+	}
+	_executeSync() {
+		throw new Error("DeferEffect is not supported in sync scheduler. Use AsyncScheduler instead.");
+	}
+	_executeAsync() {
+		return this.promise;
+	}
+};
+/**
+* Parallel effect - executes multiple effects concurrently.
+* In sync schedulers, effects are executed sequentially.
+* In async schedulers, effects are executed with Promise.all.
+*
+* @example
+* const results = yield* new ParallelEffect([new PureEffect(1), new PureEffect(2)]).run(); // [1, 2]
+*/
+var ParallelEffect = class extends Effect {
+	constructor(effects) {
+		super();
+		this.effects = effects;
+	}
+	_executeSync() {
+		return this.effects.map((e) => e.executeSync());
+	}
+	async _executeAsync() {
+		return Promise.all(this.effects.map((e) => e.executeAsync()));
+	}
+};
+/**
+* Yield effect - yields control back to the event loop.
+* This helps prevent blocking the event loop in long-running operations.
+* Only works in async schedulers; throws in sync schedulers.
+*
+* @example
+* for (let i = 0; i < 10000; i++) {
+*   doWork(i);
+*   if (i % 100 === 0) {
+*     yield* new YieldEffect().run();
+*   }
+* }
+*/
+var YieldEffect = class extends Effect {
+	_executeSync() {
+		throw new Error("YieldEffect is not supported in sync scheduler. Use AsyncScheduler instead.");
+	}
+	async _executeAsync() {
+		await new Promise((resolve) => {
+			if (typeof setImmediate !== "undefined") {
+				setImmediate(resolve);
+			} else {
+				setTimeout(resolve, 0);
+			}
+		});
+	}
+};
+/**
+* Effect factory namespace for convenience.
+* Provides static methods to create effects.
+*/
+const Effects = {
+	pure: (value) => new PureEffect(value),
+	defer: (promise) => new DeferEffect(promise),
+	parallel: (effects) => new ParallelEffect(effects),
+	yield: () => new YieldEffect()
+};
+
+//#endregion
+//#region packages/common/src/scheduler/sync-scheduler.ts
+/**
+* Create a synchronous scheduler.
+*
+* This scheduler executes generators synchronously.
+* It throws an error if an async-only effect (defer, yield) is encountered.
+*
+* @returns A SyncScheduler instance
+*
+* @example
+* const scheduler = createSyncScheduler();
+* const result = scheduler.run(function* () {
+*   const a = yield* new PureEffect(1).run();
+*   const b = yield* new PureEffect(2).run();
+*   return a + b;
+* });
+* // result = ok(3)
+*/
+const createSyncScheduler = () => {
+	const run = (generatorFn) => {
+		try {
+			const generator = generatorFn();
+			let result = generator.next();
+			while (!result.done) {
+				const effect = result.value;
+				const effectResult = effect.executeSync();
+				result = generator.next(EffectReturn.wrap(effectResult));
+			}
+			return ok(result.value);
+		} catch (error) {
+			if (isSchedulerError(error)) {
+				return err(error);
+			}
+			return err(createSchedulerError(error instanceof Error ? error.message : String(error), error));
+		}
+	};
+	return { run };
+};
+/**
+* Type guard for SchedulerError.
+*/
+const isSchedulerError = (error) => {
+	return typeof error === "object" && error !== null && error.kind === "scheduler-error";
+};
+
+//#endregion
+export { CanonicalIdSchema, DeferEffect, Effect, Effects, MODULE_EXTENSION_CANDIDATES, ParallelEffect, PureEffect, YieldEffect, __resetPortableFSForTests, __resetPortableHasherForTests, buildAstPath, cachedFn, createAsyncScheduler, createCanonicalId, createCanonicalTracker, createOccurrenceTracker, createPathTracker, createPortableFS, createPortableHasher, createSchedulerError, createSyncScheduler, defineSchemaFor, generateId, getPortableFS, getPortableHasher, isExternalSpecifier, isRelativeSpecifier, normalizePath, once, resetPortableForTests, resolveRelativeImportWithExistenceCheck, resolveRelativeImportWithReferences, runtime, spawn };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["isSchedulerError","pureValue: T","promise: Promise<T>","effects: readonly Effect<unknown>[]"],"sources":["../src/scheduler/types.ts","../src/scheduler/async-scheduler.ts","../src/scheduler/effect.ts","../src/scheduler/sync-scheduler.ts"],"sourcesContent":["import type { Result } from \"neverthrow\";\n\n/**\n * Abstract base class for all effects.\n * Effects encapsulate both the data and the execution logic.\n *\n * @template TResult - The type of value this effect produces when executed\n *\n * @example\n * ```typescript\n * function* myGenerator() {\n *   const value = yield* new PureEffect(42).run();\n *   return value; // 42\n * }\n * ```\n */\nexport abstract class Effect<TResult = unknown> {\n  /**\n   * Execute the effect synchronously and return the result.\n   */\n  executeSync(): TResult {\n    return this._executeSync();\n  }\n\n  /**\n   * Execute the effect asynchronously and return the result.\n   */\n  async executeAsync(): Promise<TResult> {\n    return this._executeAsync();\n  }\n\n  /**\n   * Returns a generator that yields this effect and returns the result.\n   * Enables the `yield*` pattern for cleaner effect handling.\n   *\n   * @example\n   * ```typescript\n   * const value = yield* effect.run();\n   * ```\n   */\n  *run(): Generator<Effect<TResult>, TResult, EffectReturn> {\n    return EffectReturn.unwrap((yield this) as EffectReturn<TResult>);\n  }\n\n  /**\n   * Internal synchronous execution logic.\n   * Subclasses must implement this method.\n   */\n  protected abstract _executeSync(): TResult;\n\n  /**\n   * Internal asynchronous execution logic.\n   * Subclasses must implement this method.\n   */\n  protected abstract _executeAsync(): Promise<TResult>;\n}\n\nconst EFFECT_RETURN = Symbol(\"EffectReturn\");\nexport class EffectReturn<TResult = unknown> {\n  private readonly [EFFECT_RETURN]: TResult;\n\n  private constructor(value: TResult) {\n    this[EFFECT_RETURN] = value;\n  }\n\n  static wrap<TResult>(value: TResult): EffectReturn<TResult> {\n    return new EffectReturn(value);\n  }\n\n  static unwrap<TResult>(value: EffectReturn<TResult>): TResult {\n    return value[EFFECT_RETURN];\n  }\n}\n\n/**\n * Extract the result type from an Effect.\n */\nexport type EffectResult<E> = E extends Effect<infer T> ? T : never;\n\n/**\n * Generator type that yields Effects.\n */\nexport type EffectGenerator<TReturn> = Generator<Effect, TReturn, EffectReturn>;\n\n/**\n * Generator function type that creates an EffectGenerator.\n */\nexport type EffectGeneratorFn<TReturn> = () => EffectGenerator<TReturn>;\n\n/**\n * Error type for scheduler operations.\n */\nexport type SchedulerError = {\n  readonly kind: \"scheduler-error\";\n  readonly message: string;\n  readonly cause?: unknown;\n};\n\n/**\n * Create a SchedulerError.\n */\nexport const createSchedulerError = (message: string, cause?: unknown): SchedulerError => ({\n  kind: \"scheduler-error\",\n  message,\n  cause,\n});\n\n/**\n * Synchronous scheduler interface.\n * Throws if an async-only effect (defer, yield) is encountered.\n */\nexport interface SyncScheduler {\n  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Result<TReturn, SchedulerError>;\n}\n\n/**\n * Asynchronous scheduler interface.\n * Handles all effect types including defer, yield, and parallel.\n */\nexport interface AsyncScheduler {\n  run<TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Promise<Result<TReturn, SchedulerError>>;\n}\n","import { err, ok, type Result } from \"neverthrow\";\nimport type { AsyncScheduler, Effect, EffectGeneratorFn, SchedulerError } from \"./types\";\nimport { createSchedulerError, EffectReturn } from \"./types\";\n\n/**\n * Create an asynchronous scheduler.\n *\n * This scheduler can handle all effect types including defer and yield.\n * Parallel effects are executed concurrently using Promise.all.\n *\n * @returns An AsyncScheduler instance\n *\n * @example\n * const scheduler = createAsyncScheduler();\n * const result = await scheduler.run(function* () {\n *   const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();\n *   yield* new YieldEffect().run(); // Yield to event loop\n *   return data;\n * });\n */\nexport const createAsyncScheduler = (): AsyncScheduler => {\n  const run = async <TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Promise<Result<TReturn, SchedulerError>> => {\n    try {\n      const generator = generatorFn();\n      let result = generator.next();\n\n      while (!result.done) {\n        const effect = result.value as Effect<unknown>;\n        const effectResult = await effect.executeAsync();\n        result = generator.next(EffectReturn.wrap(effectResult));\n      }\n\n      return ok(result.value);\n    } catch (error) {\n      if (isSchedulerError(error)) {\n        return err(error);\n      }\n      return err(createSchedulerError(error instanceof Error ? error.message : String(error), error));\n    }\n  };\n\n  return { run };\n};\n\n/**\n * Type guard for SchedulerError.\n */\nconst isSchedulerError = (error: unknown): error is SchedulerError => {\n  return typeof error === \"object\" && error !== null && (error as SchedulerError).kind === \"scheduler-error\";\n};\n","import { Effect } from \"./types\";\n\n/**\n * Pure effect - returns a value immediately.\n * Works in both sync and async schedulers.\n *\n * @example\n * const result = yield* new PureEffect(42).run(); // 42\n */\nexport class PureEffect<T> extends Effect<T> {\n  constructor(readonly pureValue: T) {\n    super();\n  }\n\n  protected _executeSync(): T {\n    return this.pureValue;\n  }\n\n  protected _executeAsync(): Promise<T> {\n    return Promise.resolve(this.pureValue);\n  }\n}\n\n/**\n * Defer effect - wraps a Promise for async execution.\n * Only works in async schedulers; throws in sync schedulers.\n *\n * @example\n * const data = yield* new DeferEffect(fetch('/api/data').then(r => r.json())).run();\n */\nexport class DeferEffect<T> extends Effect<T> {\n  constructor(readonly promise: Promise<T>) {\n    super();\n  }\n\n  protected _executeSync(): T {\n    throw new Error(\"DeferEffect is not supported in sync scheduler. Use AsyncScheduler instead.\");\n  }\n\n  protected _executeAsync(): Promise<T> {\n    return this.promise;\n  }\n}\n\n/**\n * Parallel effect - executes multiple effects concurrently.\n * In sync schedulers, effects are executed sequentially.\n * In async schedulers, effects are executed with Promise.all.\n *\n * @example\n * const results = yield* new ParallelEffect([new PureEffect(1), new PureEffect(2)]).run(); // [1, 2]\n */\nexport class ParallelEffect extends Effect<readonly unknown[]> {\n  constructor(readonly effects: readonly Effect<unknown>[]) {\n    super();\n  }\n\n  protected _executeSync(): readonly unknown[] {\n    return this.effects.map((e) => e.executeSync());\n  }\n\n  protected async _executeAsync(): Promise<readonly unknown[]> {\n    return Promise.all(this.effects.map((e) => e.executeAsync()));\n  }\n}\n\n/**\n * Yield effect - yields control back to the event loop.\n * This helps prevent blocking the event loop in long-running operations.\n * Only works in async schedulers; throws in sync schedulers.\n *\n * @example\n * for (let i = 0; i < 10000; i++) {\n *   doWork(i);\n *   if (i % 100 === 0) {\n *     yield* new YieldEffect().run();\n *   }\n * }\n */\nexport class YieldEffect extends Effect<void> {\n  protected _executeSync(): void {\n    throw new Error(\"YieldEffect is not supported in sync scheduler. Use AsyncScheduler instead.\");\n  }\n\n  protected async _executeAsync(): Promise<void> {\n    await new Promise<void>((resolve) => {\n      if (typeof setImmediate !== \"undefined\") {\n        setImmediate(resolve);\n      } else {\n        setTimeout(resolve, 0);\n      }\n    });\n  }\n}\n\n/**\n * Effect factory namespace for convenience.\n * Provides static methods to create effects.\n */\nexport const Effects = {\n  /**\n   * Create a pure effect that returns a value immediately.\n   */\n  pure: <T>(value: T): PureEffect<T> => new PureEffect(value),\n\n  /**\n   * Create a defer effect that wraps a Promise.\n   */\n  defer: <T>(promise: Promise<T>): DeferEffect<T> => new DeferEffect(promise),\n\n  /**\n   * Create a parallel effect that executes multiple effects concurrently.\n   */\n  parallel: (effects: readonly Effect<unknown>[]): ParallelEffect => new ParallelEffect(effects),\n\n  /**\n   * Create a yield effect that returns control to the event loop.\n   */\n  yield: (): YieldEffect => new YieldEffect(),\n} as const;\n","import { err, ok, type Result } from \"neverthrow\";\nimport type { Effect, EffectGeneratorFn, SchedulerError, SyncScheduler } from \"./types\";\nimport { createSchedulerError, EffectReturn } from \"./types\";\n\n/**\n * Create a synchronous scheduler.\n *\n * This scheduler executes generators synchronously.\n * It throws an error if an async-only effect (defer, yield) is encountered.\n *\n * @returns A SyncScheduler instance\n *\n * @example\n * const scheduler = createSyncScheduler();\n * const result = scheduler.run(function* () {\n *   const a = yield* new PureEffect(1).run();\n *   const b = yield* new PureEffect(2).run();\n *   return a + b;\n * });\n * // result = ok(3)\n */\nexport const createSyncScheduler = (): SyncScheduler => {\n  const run = <TReturn>(generatorFn: EffectGeneratorFn<TReturn>): Result<TReturn, SchedulerError> => {\n    try {\n      const generator = generatorFn();\n      let result = generator.next();\n\n      while (!result.done) {\n        const effect = result.value as Effect<unknown>;\n        const effectResult = effect.executeSync();\n        result = generator.next(EffectReturn.wrap(effectResult));\n      }\n\n      return ok(result.value);\n    } catch (error) {\n      if (isSchedulerError(error)) {\n        return err(error);\n      }\n      return err(createSchedulerError(error instanceof Error ? error.message : String(error), error));\n    }\n  };\n\n  return { run };\n};\n\n/**\n * Type guard for SchedulerError.\n */\nconst isSchedulerError = (error: unknown): error is SchedulerError => {\n  return typeof error === \"object\" && error !== null && (error as SchedulerError).kind === \"scheduler-error\";\n};\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soda-gql/common",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -17,40 +17,43 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
+      "@soda-gql": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs",
       "default": "./dist/index.mjs"
     },
     "./portable": {
-      "development": "./src/portable/index.ts",
+      "@soda-gql": "./src/portable/index.ts",
       "types": "./dist/portable/index.d.mts",
       "import": "./dist/portable/index.mjs",
       "require": "./dist/portable/index.cjs",
       "default": "./dist/portable/index.mjs"
     },
     "./canonical-id": {
-      "development": "./src/canonical-id/index.ts",
+      "@soda-gql": "./src/canonical-id/index.ts",
       "types": "./dist/canonical-id/index.d.mts",
       "import": "./dist/canonical-id/index.mjs",
       "require": "./dist/canonical-id/index.cjs",
       "default": "./dist/canonical-id/index.mjs"
     },
     "./utils": {
-      "development": "./src/utils/index.ts",
+      "@soda-gql": "./src/utils/index.ts",
       "types": "./dist/utils/index.d.mts",
       "import": "./dist/utils/index.mjs",
       "require": "./dist/utils/index.cjs",
       "default": "./dist/utils/index.mjs"
     },
     "./zod": {
-      "development": "./src/zod/index.ts",
+      "@soda-gql": "./src/zod/index.ts",
       "types": "./dist/zod/index.d.mts",
       "import": "./dist/zod/index.mjs",
       "require": "./dist/zod/index.cjs",
       "default": "./dist/zod/index.mjs"
     },
+    "./test": {
+      "@soda-gql": "./test/export.ts"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {