@soda-gql/sdk 0.10.2

package/README.md

@@ -0,0 +1,160 @@
+# @soda-gql/sdk
+
+[![npm version](https://badge.fury.io/js/@soda-gql%2Fsdk.svg)](https://badge.fury.io/js/@soda-gql%2Fsdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Programmatic API for soda-gql prebuild operations.
+
+## Installation
+
+```bash
+bun add @soda-gql/sdk
+```
+
+## Overview
+
+This package provides a programmatic interface to soda-gql's build system, allowing external tools
+and build plugins to execute artifact generation without invoking the CLI.
+
+**Key Features:**
+
+- Synchronous and asynchronous build APIs
+- Optional context transformation for modifying composer context
+- Configurable build options (force rebuild, evaluator ID, entrypoints override)
+- Comprehensive error handling with typed Result
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { prebuild, prebuildAsync } from "@soda-gql/sdk";
+
+// Synchronous build
+const result = prebuild({
+  configPath: "./soda-gql.config.ts",
+});
+
+if (result.isOk()) {
+  const { artifact } = result.value;
+  console.log(`Built ${Object.keys(artifact.elements).length} elements`);
+} else {
+  console.error("Build failed:", result.error);
+}
+
+// Asynchronous build
+const asyncResult = await prebuildAsync({
+  configPath: "./soda-gql.config.ts",
+});
+```
+
+### With Context Transformer
+
+```typescript
+import { prebuildAsync } from "@soda-gql/sdk";
+
+const result = await prebuildAsync({
+  configPath: "./soda-gql.config.ts",
+  contextTransformer: (context) => ({
+    ...context,
+    // Add custom context properties
+    buildId: process.env.BUILD_ID,
+    environment: "production",
+  }),
+});
+```
+
+### With Build Options
+
+```typescript
+import { prebuildAsync } from "@soda-gql/sdk";
+
+const result = await prebuildAsync({
+  configPath: "./soda-gql.config.ts",
+  force: true, // Force rebuild, ignore cache
+  evaluatorId: "my-build", // Custom evaluator ID for cache isolation
+  entrypointsOverride: ["./src/graphql/**/*.ts"], // Override config.include
+});
+```
+
+## API Reference
+
+### `prebuild(options: PrebuildOptions): Result<PrebuildResult, PrebuildError>`
+
+Synchronously builds GraphQL artifacts based on the provided configuration.
+
+### `prebuildAsync(options: PrebuildOptions): Promise<Result<PrebuildResult, PrebuildError>>`
+
+Asynchronously builds GraphQL artifacts. Preferred for build plugins and tools.
+
+### Types
+
+#### `PrebuildOptions`
+
+| Property             | Type                      | Required | Description                                    |
+| -------------------- | ------------------------- | -------- | ---------------------------------------------- |
+| `configPath`         | `string`                  | Yes      | Path to soda-gql config file                   |
+| `contextTransformer` | `ContextTransformer`      | No       | Function to modify composer context            |
+| `force`              | `boolean`                 | No       | Force rebuild, ignore cache (default: false)   |
+| `evaluatorId`        | `string`                  | No       | Unique evaluator ID (default: "default")       |
+| `entrypointsOverride`| `string[] \| Set<string>` | No       | Override config.include patterns               |
+
+#### `PrebuildResult`
+
+```typescript
+interface PrebuildResult {
+  artifact: BuilderArtifact;
+}
+```
+
+#### `PrebuildError`
+
+Union type: `ConfigError | BuilderError`
+
+#### `ContextTransformer`
+
+```typescript
+type ContextTransformer = (
+  context: Record<string, unknown>
+) => Record<string, unknown>;
+```
+
+## Session Lifecycle
+
+`prebuild` and `prebuildAsync` internally create a BuilderSession and always call `dispose()` after
+build completion (in a finally block).
+
+### What `dispose()` does:
+
+1. **Cache Persistence**: Saves incremental build cache to `node_modules/.cache/soda-gql/builder/cache.json`
+2. **Exit Handler Cleanup**: Unregisters from process exit handler to prevent duplicate saves
+
+### Notes:
+
+- When using SDK, `dispose()` is called automatically - no manual cleanup needed
+- Even if build fails, dispose is guaranteed to run via finally block
+- Cache is shared across builds with the same `evaluatorId`
+
+## Limitations
+
+### Concurrent Execution
+
+Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+`contextTransformer` options. The context transformer uses global state and concurrent calls
+may result in incorrect context being applied.
+
+**Safe patterns:**
+
+- Sequential builds with different transformers
+- Concurrent builds without transformers
+- Concurrent builds with the same transformer
+
+## Related Packages
+
+- [@soda-gql/builder](../builder) - Core build system
+- [@soda-gql/config](../config) - Configuration loading
+- [@soda-gql/core](../core) - GraphQL composition primitives
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,113 @@
+let __soda_gql_builder = require("@soda-gql/builder");
+let __soda_gql_config = require("@soda-gql/config");
+let __soda_gql_core__internal = require("@soda-gql/core/_internal");
+let neverthrow = require("neverthrow");
+
+//#region packages/sdk/src/prebuild.ts
+/**
+* Prebuild API for programmatic artifact generation.
+* @module
+*/
+/**
+* Build artifact synchronously from a config file.
+*
+* @remarks
+* **Concurrent Execution Warning**: This function uses global state for context transformation.
+* Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+* `contextTransformer` options. Sequential execution is safe.
+*
+* **Session Lifecycle**: This function automatically handles session lifecycle:
+* - Creates a BuilderSession with the resolved config
+* - Calls `session.dispose()` in a finally block to:
+*   - Save incremental build cache to disk
+*   - Unregister from process exit handler
+* - Clears context transformer state after build
+*
+* @param options - Prebuild options including config path and optional transformer
+* @returns Result containing the built artifact or an error
+*
+* @example
+* ```typescript
+* const result = prebuild({ configPath: './soda-gql.config.ts' });
+* if (result.isOk()) {
+*   console.log(result.value.artifact.elements);
+* }
+* ```
+*/
+const prebuild = (options) => {
+	const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;
+	const configResult = (0, __soda_gql_config.loadConfig)(configPath);
+	if (configResult.isErr()) {
+		return (0, neverthrow.err)(configResult.error);
+	}
+	const config = configResult.value;
+	const session = (0, __soda_gql_builder.createBuilderSession)({
+		config,
+		evaluatorId,
+		entrypointsOverride
+	});
+	try {
+		if (contextTransformer) {
+			(0, __soda_gql_core__internal.setContextTransformer)(contextTransformer);
+		}
+		const result = session.build({ force });
+		return result.map((artifact) => ({ artifact }));
+	} finally {
+		(0, __soda_gql_core__internal.clearContextTransformer)();
+		session.dispose();
+	}
+};
+/**
+* Build artifact asynchronously from a config file.
+*
+* @remarks
+* **Concurrent Execution Warning**: This function uses global state for context transformation.
+* Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+* `contextTransformer` options. Sequential execution is safe.
+*
+* **Session Lifecycle**: This function automatically handles session lifecycle:
+* - Creates a BuilderSession with the resolved config
+* - Calls `session.dispose()` in a finally block to:
+*   - Save incremental build cache to disk
+*   - Unregister from process exit handler
+* - Clears context transformer state after build
+*
+* @param options - Prebuild options including config path and optional transformer
+* @returns Promise resolving to Result containing the built artifact or an error
+*
+* @example
+* ```typescript
+* const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });
+* if (result.isOk()) {
+*   console.log(result.value.artifact.elements);
+* }
+* ```
+*/
+const prebuildAsync = async (options) => {
+	const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;
+	const configResult = (0, __soda_gql_config.loadConfig)(configPath);
+	if (configResult.isErr()) {
+		return (0, neverthrow.err)(configResult.error);
+	}
+	const config = configResult.value;
+	const session = (0, __soda_gql_builder.createBuilderSession)({
+		config,
+		evaluatorId,
+		entrypointsOverride
+	});
+	try {
+		if (contextTransformer) {
+			(0, __soda_gql_core__internal.setContextTransformer)(contextTransformer);
+		}
+		const result = await session.buildAsync({ force });
+		return result.map((artifact) => ({ artifact }));
+	} finally {
+		(0, __soda_gql_core__internal.clearContextTransformer)();
+		session.dispose();
+	}
+};
+
+//#endregion
+exports.prebuild = prebuild;
+exports.prebuildAsync = prebuildAsync;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/prebuild.ts"],"sourcesContent":["/**\n * Prebuild API for programmatic artifact generation.\n * @module\n */\n\nimport { type BuilderArtifact, type BuilderError, createBuilderSession } from \"@soda-gql/builder\";\nimport { type ConfigError, loadConfig } from \"@soda-gql/config\";\nimport { type ContextTransformer, clearContextTransformer, setContextTransformer } from \"@soda-gql/core/_internal\";\nimport { err, type Result } from \"neverthrow\";\n\nexport type { ContextTransformer };\n\n/**\n * Error type for prebuild operations.\n * Can be either a config loading error or a builder error.\n */\nexport type PrebuildError = ConfigError | BuilderError;\n\n/**\n * Options for prebuild functions.\n */\nexport interface PrebuildOptions {\n  /** Path to soda-gql config file */\n  configPath: string;\n  /** Optional context transformer to modify composer context */\n  contextTransformer?: ContextTransformer;\n  /** Unique identifier for this evaluator instance (default: \"default\") */\n  evaluatorId?: string;\n  /** Override entrypoints from config.include */\n  entrypointsOverride?: readonly string[] | ReadonlySet<string>;\n  /** Force rebuild even if no changes detected */\n  force?: boolean;\n}\n\n/**\n * Result of prebuild operations.\n */\nexport interface PrebuildResult {\n  artifact: BuilderArtifact;\n}\n\n/**\n * Build artifact synchronously from a config file.\n *\n * @remarks\n * **Concurrent Execution Warning**: This function uses global state for context transformation.\n * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different\n * `contextTransformer` options. Sequential execution is safe.\n *\n * **Session Lifecycle**: This function automatically handles session lifecycle:\n * - Creates a BuilderSession with the resolved config\n * - Calls `session.dispose()` in a finally block to:\n *   - Save incremental build cache to disk\n *   - Unregister from process exit handler\n * - Clears context transformer state after build\n *\n * @param options - Prebuild options including config path and optional transformer\n * @returns Result containing the built artifact or an error\n *\n * @example\n * ```typescript\n * const result = prebuild({ configPath: './soda-gql.config.ts' });\n * if (result.isOk()) {\n *   console.log(result.value.artifact.elements);\n * }\n * ```\n */\nexport const prebuild = (options: PrebuildOptions): Result<PrebuildResult, PrebuildError> => {\n  const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;\n\n  // Load config from file path\n  const configResult = loadConfig(configPath);\n  if (configResult.isErr()) {\n    return err(configResult.error);\n  }\n  const config = configResult.value;\n\n  const session = createBuilderSession({ config, evaluatorId, entrypointsOverride });\n\n  try {\n    if (contextTransformer) {\n      setContextTransformer(contextTransformer);\n    }\n    const result = session.build({ force });\n    return result.map((artifact) => ({ artifact }));\n  } finally {\n    clearContextTransformer();\n    session.dispose();\n  }\n};\n\n/**\n * Build artifact asynchronously from a config file.\n *\n * @remarks\n * **Concurrent Execution Warning**: This function uses global state for context transformation.\n * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different\n * `contextTransformer` options. Sequential execution is safe.\n *\n * **Session Lifecycle**: This function automatically handles session lifecycle:\n * - Creates a BuilderSession with the resolved config\n * - Calls `session.dispose()` in a finally block to:\n *   - Save incremental build cache to disk\n *   - Unregister from process exit handler\n * - Clears context transformer state after build\n *\n * @param options - Prebuild options including config path and optional transformer\n * @returns Promise resolving to Result containing the built artifact or an error\n *\n * @example\n * ```typescript\n * const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });\n * if (result.isOk()) {\n *   console.log(result.value.artifact.elements);\n * }\n * ```\n */\nexport const prebuildAsync = async (options: PrebuildOptions): Promise<Result<PrebuildResult, PrebuildError>> => {\n  const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;\n\n  // Load config from file path (sync - no async version available)\n  const configResult = loadConfig(configPath);\n  if (configResult.isErr()) {\n    return err(configResult.error);\n  }\n  const config = configResult.value;\n\n  const session = createBuilderSession({ config, evaluatorId, entrypointsOverride });\n\n  try {\n    if (contextTransformer) {\n      setContextTransformer(contextTransformer);\n    }\n    const result = await session.buildAsync({ force });\n    return result.map((artifact) => ({ artifact }));\n  } finally {\n    clearContextTransformer();\n    session.dispose();\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,YAAY,YAAoE;CAC3F,MAAM,EAAE,YAAY,oBAAoB,aAAa,qBAAqB,UAAU;CAGpF,MAAM,iDAA0B,WAAW;AAC3C,KAAI,aAAa,OAAO,EAAE;AACxB,6BAAW,aAAa,MAAM;;CAEhC,MAAM,SAAS,aAAa;CAE5B,MAAM,uDAA+B;EAAE;EAAQ;EAAa;EAAqB,CAAC;AAElF,KAAI;AACF,MAAI,oBAAoB;AACtB,wDAAsB,mBAAmB;;EAE3C,MAAM,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC;AACvC,SAAO,OAAO,KAAK,cAAc,EAAE,UAAU,EAAE;WACvC;AACR,0DAAyB;AACzB,UAAQ,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BrB,MAAa,gBAAgB,OAAO,YAA6E;CAC/G,MAAM,EAAE,YAAY,oBAAoB,aAAa,qBAAqB,UAAU;CAGpF,MAAM,iDAA0B,WAAW;AAC3C,KAAI,aAAa,OAAO,EAAE;AACxB,6BAAW,aAAa,MAAM;;CAEhC,MAAM,SAAS,aAAa;CAE5B,MAAM,uDAA+B;EAAE;EAAQ;EAAa;EAAqB,CAAC;AAElF,KAAI;AACF,MAAI,oBAAoB;AACtB,wDAAsB,mBAAmB;;EAE3C,MAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,OAAO,CAAC;AAClD,SAAO,OAAO,KAAK,cAAc,EAAE,UAAU,EAAE;WACvC;AACR,0DAAyB;AACzB,UAAQ,SAAS"}

package/dist/index.d.cts

@@ -0,0 +1,90 @@
+import { BuilderArtifact, BuilderError } from "@soda-gql/builder";
+import { ConfigError } from "@soda-gql/config";
+import { ContextTransformer } from "@soda-gql/core/_internal";
+import { Result } from "neverthrow";
+
+//#region packages/sdk/src/prebuild.d.ts
+
+/**
+ * Error type for prebuild operations.
+ * Can be either a config loading error or a builder error.
+ */
+type PrebuildError = ConfigError | BuilderError;
+/**
+ * Options for prebuild functions.
+ */
+interface PrebuildOptions {
+  /** Path to soda-gql config file */
+  configPath: string;
+  /** Optional context transformer to modify composer context */
+  contextTransformer?: ContextTransformer;
+  /** Unique identifier for this evaluator instance (default: "default") */
+  evaluatorId?: string;
+  /** Override entrypoints from config.include */
+  entrypointsOverride?: readonly string[] | ReadonlySet<string>;
+  /** Force rebuild even if no changes detected */
+  force?: boolean;
+}
+/**
+ * Result of prebuild operations.
+ */
+interface PrebuildResult {
+  artifact: BuilderArtifact;
+}
+/**
+ * Build artifact synchronously from a config file.
+ *
+ * @remarks
+ * **Concurrent Execution Warning**: This function uses global state for context transformation.
+ * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+ * `contextTransformer` options. Sequential execution is safe.
+ *
+ * **Session Lifecycle**: This function automatically handles session lifecycle:
+ * - Creates a BuilderSession with the resolved config
+ * - Calls `session.dispose()` in a finally block to:
+ *   - Save incremental build cache to disk
+ *   - Unregister from process exit handler
+ * - Clears context transformer state after build
+ *
+ * @param options - Prebuild options including config path and optional transformer
+ * @returns Result containing the built artifact or an error
+ *
+ * @example
+ * ```typescript
+ * const result = prebuild({ configPath: './soda-gql.config.ts' });
+ * if (result.isOk()) {
+ *   console.log(result.value.artifact.elements);
+ * }
+ * ```
+ */
+declare const prebuild: (options: PrebuildOptions) => Result<PrebuildResult, PrebuildError>;
+/**
+ * Build artifact asynchronously from a config file.
+ *
+ * @remarks
+ * **Concurrent Execution Warning**: This function uses global state for context transformation.
+ * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+ * `contextTransformer` options. Sequential execution is safe.
+ *
+ * **Session Lifecycle**: This function automatically handles session lifecycle:
+ * - Creates a BuilderSession with the resolved config
+ * - Calls `session.dispose()` in a finally block to:
+ *   - Save incremental build cache to disk
+ *   - Unregister from process exit handler
+ * - Clears context transformer state after build
+ *
+ * @param options - Prebuild options including config path and optional transformer
+ * @returns Promise resolving to Result containing the built artifact or an error
+ *
+ * @example
+ * ```typescript
+ * const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });
+ * if (result.isOk()) {
+ *   console.log(result.value.artifact.elements);
+ * }
+ * ```
+ */
+declare const prebuildAsync: (options: PrebuildOptions) => Promise<Result<PrebuildResult, PrebuildError>>;
+//#endregion
+export { type ContextTransformer, type PrebuildError, type PrebuildOptions, type PrebuildResult, prebuild, prebuildAsync };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/prebuild.ts"],"sourcesContent":[],"mappings":";;;;;;;AAmEA;;;;AAAoD,KAnDxC,aAAA,GAAgB,WAmDwB,GAnDV,YAmDU;;AAkDpD;;AAA8E,UAhG7D,eAAA,CAgG6D;EAAgB;EAAvB,UAAA,EAAA,MAAA;EAAR;EAAO,kBAAA,CAAA,EA5F/C,kBA4F+C;;;;4CAxF1B;;;;;;;UAQ3B,cAAA;YACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6BC,oBAAqB,oBAAkB,OAAO,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkD9D,yBAAgC,oBAAkB,QAAQ,OAAO,gBAAgB"}

package/dist/index.d.mts

@@ -0,0 +1,90 @@
+import { BuilderArtifact, BuilderError } from "@soda-gql/builder";
+import { ConfigError } from "@soda-gql/config";
+import { ContextTransformer } from "@soda-gql/core/_internal";
+import { Result } from "neverthrow";
+
+//#region packages/sdk/src/prebuild.d.ts
+
+/**
+ * Error type for prebuild operations.
+ * Can be either a config loading error or a builder error.
+ */
+type PrebuildError = ConfigError | BuilderError;
+/**
+ * Options for prebuild functions.
+ */
+interface PrebuildOptions {
+  /** Path to soda-gql config file */
+  configPath: string;
+  /** Optional context transformer to modify composer context */
+  contextTransformer?: ContextTransformer;
+  /** Unique identifier for this evaluator instance (default: "default") */
+  evaluatorId?: string;
+  /** Override entrypoints from config.include */
+  entrypointsOverride?: readonly string[] | ReadonlySet<string>;
+  /** Force rebuild even if no changes detected */
+  force?: boolean;
+}
+/**
+ * Result of prebuild operations.
+ */
+interface PrebuildResult {
+  artifact: BuilderArtifact;
+}
+/**
+ * Build artifact synchronously from a config file.
+ *
+ * @remarks
+ * **Concurrent Execution Warning**: This function uses global state for context transformation.
+ * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+ * `contextTransformer` options. Sequential execution is safe.
+ *
+ * **Session Lifecycle**: This function automatically handles session lifecycle:
+ * - Creates a BuilderSession with the resolved config
+ * - Calls `session.dispose()` in a finally block to:
+ *   - Save incremental build cache to disk
+ *   - Unregister from process exit handler
+ * - Clears context transformer state after build
+ *
+ * @param options - Prebuild options including config path and optional transformer
+ * @returns Result containing the built artifact or an error
+ *
+ * @example
+ * ```typescript
+ * const result = prebuild({ configPath: './soda-gql.config.ts' });
+ * if (result.isOk()) {
+ *   console.log(result.value.artifact.elements);
+ * }
+ * ```
+ */
+declare const prebuild: (options: PrebuildOptions) => Result<PrebuildResult, PrebuildError>;
+/**
+ * Build artifact asynchronously from a config file.
+ *
+ * @remarks
+ * **Concurrent Execution Warning**: This function uses global state for context transformation.
+ * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+ * `contextTransformer` options. Sequential execution is safe.
+ *
+ * **Session Lifecycle**: This function automatically handles session lifecycle:
+ * - Creates a BuilderSession with the resolved config
+ * - Calls `session.dispose()` in a finally block to:
+ *   - Save incremental build cache to disk
+ *   - Unregister from process exit handler
+ * - Clears context transformer state after build
+ *
+ * @param options - Prebuild options including config path and optional transformer
+ * @returns Promise resolving to Result containing the built artifact or an error
+ *
+ * @example
+ * ```typescript
+ * const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });
+ * if (result.isOk()) {
+ *   console.log(result.value.artifact.elements);
+ * }
+ * ```
+ */
+declare const prebuildAsync: (options: PrebuildOptions) => Promise<Result<PrebuildResult, PrebuildError>>;
+//#endregion
+export { type ContextTransformer, type PrebuildError, type PrebuildOptions, type PrebuildResult, prebuild, prebuildAsync };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/prebuild.ts"],"sourcesContent":[],"mappings":";;;;;;;AAmEA;;;;AAAoD,KAnDxC,aAAA,GAAgB,WAmDwB,GAnDV,YAmDU;;AAkDpD;;AAA8E,UAhG7D,eAAA,CAgG6D;EAAgB;EAAvB,UAAA,EAAA,MAAA;EAAR;EAAO,kBAAA,CAAA,EA5F/C,kBA4F+C;;;;4CAxF1B;;;;;;;UAQ3B,cAAA;YACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6BC,oBAAqB,oBAAkB,OAAO,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkD9D,yBAAgC,oBAAkB,QAAQ,OAAO,gBAAgB"}

package/dist/index.mjs

@@ -0,0 +1,112 @@
+import { createBuilderSession } from "@soda-gql/builder";
+import { loadConfig } from "@soda-gql/config";
+import { clearContextTransformer, setContextTransformer } from "@soda-gql/core/_internal";
+import { err } from "neverthrow";
+
+//#region packages/sdk/src/prebuild.ts
+/**
+* Prebuild API for programmatic artifact generation.
+* @module
+*/
+/**
+* Build artifact synchronously from a config file.
+*
+* @remarks
+* **Concurrent Execution Warning**: This function uses global state for context transformation.
+* Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+* `contextTransformer` options. Sequential execution is safe.
+*
+* **Session Lifecycle**: This function automatically handles session lifecycle:
+* - Creates a BuilderSession with the resolved config
+* - Calls `session.dispose()` in a finally block to:
+*   - Save incremental build cache to disk
+*   - Unregister from process exit handler
+* - Clears context transformer state after build
+*
+* @param options - Prebuild options including config path and optional transformer
+* @returns Result containing the built artifact or an error
+*
+* @example
+* ```typescript
+* const result = prebuild({ configPath: './soda-gql.config.ts' });
+* if (result.isOk()) {
+*   console.log(result.value.artifact.elements);
+* }
+* ```
+*/
+const prebuild = (options) => {
+	const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;
+	const configResult = loadConfig(configPath);
+	if (configResult.isErr()) {
+		return err(configResult.error);
+	}
+	const config = configResult.value;
+	const session = createBuilderSession({
+		config,
+		evaluatorId,
+		entrypointsOverride
+	});
+	try {
+		if (contextTransformer) {
+			setContextTransformer(contextTransformer);
+		}
+		const result = session.build({ force });
+		return result.map((artifact) => ({ artifact }));
+	} finally {
+		clearContextTransformer();
+		session.dispose();
+	}
+};
+/**
+* Build artifact asynchronously from a config file.
+*
+* @remarks
+* **Concurrent Execution Warning**: This function uses global state for context transformation.
+* Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different
+* `contextTransformer` options. Sequential execution is safe.
+*
+* **Session Lifecycle**: This function automatically handles session lifecycle:
+* - Creates a BuilderSession with the resolved config
+* - Calls `session.dispose()` in a finally block to:
+*   - Save incremental build cache to disk
+*   - Unregister from process exit handler
+* - Clears context transformer state after build
+*
+* @param options - Prebuild options including config path and optional transformer
+* @returns Promise resolving to Result containing the built artifact or an error
+*
+* @example
+* ```typescript
+* const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });
+* if (result.isOk()) {
+*   console.log(result.value.artifact.elements);
+* }
+* ```
+*/
+const prebuildAsync = async (options) => {
+	const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;
+	const configResult = loadConfig(configPath);
+	if (configResult.isErr()) {
+		return err(configResult.error);
+	}
+	const config = configResult.value;
+	const session = createBuilderSession({
+		config,
+		evaluatorId,
+		entrypointsOverride
+	});
+	try {
+		if (contextTransformer) {
+			setContextTransformer(contextTransformer);
+		}
+		const result = await session.buildAsync({ force });
+		return result.map((artifact) => ({ artifact }));
+	} finally {
+		clearContextTransformer();
+		session.dispose();
+	}
+};
+
+//#endregion
+export { prebuild, prebuildAsync };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/prebuild.ts"],"sourcesContent":["/**\n * Prebuild API for programmatic artifact generation.\n * @module\n */\n\nimport { type BuilderArtifact, type BuilderError, createBuilderSession } from \"@soda-gql/builder\";\nimport { type ConfigError, loadConfig } from \"@soda-gql/config\";\nimport { type ContextTransformer, clearContextTransformer, setContextTransformer } from \"@soda-gql/core/_internal\";\nimport { err, type Result } from \"neverthrow\";\n\nexport type { ContextTransformer };\n\n/**\n * Error type for prebuild operations.\n * Can be either a config loading error or a builder error.\n */\nexport type PrebuildError = ConfigError | BuilderError;\n\n/**\n * Options for prebuild functions.\n */\nexport interface PrebuildOptions {\n  /** Path to soda-gql config file */\n  configPath: string;\n  /** Optional context transformer to modify composer context */\n  contextTransformer?: ContextTransformer;\n  /** Unique identifier for this evaluator instance (default: \"default\") */\n  evaluatorId?: string;\n  /** Override entrypoints from config.include */\n  entrypointsOverride?: readonly string[] | ReadonlySet<string>;\n  /** Force rebuild even if no changes detected */\n  force?: boolean;\n}\n\n/**\n * Result of prebuild operations.\n */\nexport interface PrebuildResult {\n  artifact: BuilderArtifact;\n}\n\n/**\n * Build artifact synchronously from a config file.\n *\n * @remarks\n * **Concurrent Execution Warning**: This function uses global state for context transformation.\n * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different\n * `contextTransformer` options. Sequential execution is safe.\n *\n * **Session Lifecycle**: This function automatically handles session lifecycle:\n * - Creates a BuilderSession with the resolved config\n * - Calls `session.dispose()` in a finally block to:\n *   - Save incremental build cache to disk\n *   - Unregister from process exit handler\n * - Clears context transformer state after build\n *\n * @param options - Prebuild options including config path and optional transformer\n * @returns Result containing the built artifact or an error\n *\n * @example\n * ```typescript\n * const result = prebuild({ configPath: './soda-gql.config.ts' });\n * if (result.isOk()) {\n *   console.log(result.value.artifact.elements);\n * }\n * ```\n */\nexport const prebuild = (options: PrebuildOptions): Result<PrebuildResult, PrebuildError> => {\n  const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;\n\n  // Load config from file path\n  const configResult = loadConfig(configPath);\n  if (configResult.isErr()) {\n    return err(configResult.error);\n  }\n  const config = configResult.value;\n\n  const session = createBuilderSession({ config, evaluatorId, entrypointsOverride });\n\n  try {\n    if (contextTransformer) {\n      setContextTransformer(contextTransformer);\n    }\n    const result = session.build({ force });\n    return result.map((artifact) => ({ artifact }));\n  } finally {\n    clearContextTransformer();\n    session.dispose();\n  }\n};\n\n/**\n * Build artifact asynchronously from a config file.\n *\n * @remarks\n * **Concurrent Execution Warning**: This function uses global state for context transformation.\n * Do not run multiple `prebuild` or `prebuildAsync` calls concurrently with different\n * `contextTransformer` options. Sequential execution is safe.\n *\n * **Session Lifecycle**: This function automatically handles session lifecycle:\n * - Creates a BuilderSession with the resolved config\n * - Calls `session.dispose()` in a finally block to:\n *   - Save incremental build cache to disk\n *   - Unregister from process exit handler\n * - Clears context transformer state after build\n *\n * @param options - Prebuild options including config path and optional transformer\n * @returns Promise resolving to Result containing the built artifact or an error\n *\n * @example\n * ```typescript\n * const result = await prebuildAsync({ configPath: './soda-gql.config.ts' });\n * if (result.isOk()) {\n *   console.log(result.value.artifact.elements);\n * }\n * ```\n */\nexport const prebuildAsync = async (options: PrebuildOptions): Promise<Result<PrebuildResult, PrebuildError>> => {\n  const { configPath, contextTransformer, evaluatorId, entrypointsOverride, force } = options;\n\n  // Load config from file path (sync - no async version available)\n  const configResult = loadConfig(configPath);\n  if (configResult.isErr()) {\n    return err(configResult.error);\n  }\n  const config = configResult.value;\n\n  const session = createBuilderSession({ config, evaluatorId, entrypointsOverride });\n\n  try {\n    if (contextTransformer) {\n      setContextTransformer(contextTransformer);\n    }\n    const result = await session.buildAsync({ force });\n    return result.map((artifact) => ({ artifact }));\n  } finally {\n    clearContextTransformer();\n    session.dispose();\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,YAAY,YAAoE;CAC3F,MAAM,EAAE,YAAY,oBAAoB,aAAa,qBAAqB,UAAU;CAGpF,MAAM,eAAe,WAAW,WAAW;AAC3C,KAAI,aAAa,OAAO,EAAE;AACxB,SAAO,IAAI,aAAa,MAAM;;CAEhC,MAAM,SAAS,aAAa;CAE5B,MAAM,UAAU,qBAAqB;EAAE;EAAQ;EAAa;EAAqB,CAAC;AAElF,KAAI;AACF,MAAI,oBAAoB;AACtB,yBAAsB,mBAAmB;;EAE3C,MAAM,SAAS,QAAQ,MAAM,EAAE,OAAO,CAAC;AACvC,SAAO,OAAO,KAAK,cAAc,EAAE,UAAU,EAAE;WACvC;AACR,2BAAyB;AACzB,UAAQ,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BrB,MAAa,gBAAgB,OAAO,YAA6E;CAC/G,MAAM,EAAE,YAAY,oBAAoB,aAAa,qBAAqB,UAAU;CAGpF,MAAM,eAAe,WAAW,WAAW;AAC3C,KAAI,aAAa,OAAO,EAAE;AACxB,SAAO,IAAI,aAAa,MAAM;;CAEhC,MAAM,SAAS,aAAa;CAE5B,MAAM,UAAU,qBAAqB;EAAE;EAAQ;EAAa;EAAqB,CAAC;AAElF,KAAI;AACF,MAAI,oBAAoB;AACtB,yBAAsB,mBAAmB;;EAE3C,MAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,OAAO,CAAC;AAClD,SAAO,OAAO,KAAK,cAAc,EAAE,UAAU,EAAE;WACvC;AACR,2BAAyB;AACzB,UAAQ,SAAS"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@soda-gql/sdk",
+  "version": "0.10.2",
+  "description": "Programmatic SDK for soda-gql CLI features",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "author": {
+    "name": "Shota Hatada",
+    "email": "shota.hatada@whatasoda.me",
+    "url": "https://github.com/whatasoda"
+  },
+  "keywords": [
+    "graphql",
+    "codegen",
+    "zero-runtime",
+    "typescript",
+    "sdk",
+    "programmatic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/whatasoda/soda-gql.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/whatasoda/soda-gql#readme",
+  "bugs": {
+    "url": "https://github.com/whatasoda/soda-gql/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "@soda-gql": "./@x-index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@soda-gql/builder": "0.10.2",
+    "@soda-gql/config": "0.10.2",
+    "@soda-gql/core": "0.10.2",
+    "neverthrow": "^8.1.1"
+  },
+  "devDependencies": {},
+  "peerDependencies": {},
+  "optionalDependencies": {}
+}