@soda-gql/core 0.8.0 → 0.8.2

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as unsafeOutputType, i as unsafeInputType, n as defineOperationRoots, o as wrapByKey, r as defineScalar, t as define } from "./schema-BbCrsNkQ.js";
+import { a as unsafeOutputType, i as unsafeInputType, n as defineOperationRoots, o as wrapByKey, r as defineScalar, t as define } from "./schema-BiYcVVvm.js";
 import { Kind, OperationTypeNode } from "graphql";
 
 //#region packages/core/src/types/type-foundation/var-ref.ts
@@ -33,6 +33,12 @@ function createVarRefFromNestedValue(value) {
 
 //#endregion
 //#region packages/core/src/composer/build-document.ts
+/**
+* Converts an assignable input value to a GraphQL AST ValueNode.
+*
+* Handles primitives, arrays, objects, and variable references.
+* Returns null for undefined values (field is omitted).
+*/
 const buildArgumentValue = (value) => {
 	if (value === void 0) return null;
 	if (value === null) return { kind: Kind.NULL };
@@ -126,6 +132,12 @@ const buildField = (field) => Object.entries(field).map(([alias, { args, field:
 		selections: buildUnionSelection(union)
 	} : void 0
 }));
+/**
+* Converts a constant value to a GraphQL AST ConstValueNode.
+*
+* Unlike `buildArgumentValue`, this only handles literal values
+* (no variable references). Used for default values.
+*/
 const buildConstValueNode = (value) => {
 	if (value === void 0) return null;
 	if (value === null) return { kind: Kind.NULL };
@@ -161,6 +173,18 @@ const buildConstValueNode = (value) => {
 	};
 	throw new Error(`Unknown value type: ${typeof value}`);
 };
+/**
+* Wraps a named type with modifiers (non-null, list).
+*
+* Modifier format: starts with `?` (nullable) or `!` (non-null),
+* followed by `[]?` or `[]!` pairs for lists.
+*
+* @example
+* - `"!"` → `String!`
+* - `"?"` → `String`
+* - `"![]!"` → `[String!]!`
+* - `"?[]?"` → `[String]`
+*/
 const buildWithTypeModifier = (modifier, buildType) => {
 	const baseType = buildType();
 	if (modifier === "?") return baseType;
@@ -238,6 +262,9 @@ const buildVariables = (variables) => {
 		}))
 	}));
 };
+/**
+* Converts an operation type string to a GraphQL AST OperationTypeNode.
+*/
 const buildOperationTypeNode = (operation) => {
 	switch (operation) {
 		case "query": return OperationTypeNode.QUERY;
@@ -246,6 +273,16 @@ const buildOperationTypeNode = (operation) => {
 		default: throw new Error(`Unknown operation type: ${operation}`);
 	}
 };
+/**
+* Builds a TypedDocumentNode from operation options.
+*
+* This is the main entry point for converting field selections into
+* a GraphQL document AST. The result can be used with any GraphQL
+* client that supports TypedDocumentNode.
+*
+* @param options - Operation configuration (name, type, variables, fields)
+* @returns TypedDocumentNode with inferred input/output types
+*/
 const buildDocument = (options) => {
 	const { operationName, operationType, variables, fields } = options;
 	return {
@@ -387,6 +424,18 @@ const ensureCacheMapBySchema = (schema) => {
 	cacheMapBySchema.set(schema, cacheMap);
 	return cacheMap;
 };
+/**
+* Creates field selection factories for a given object type.
+*
+* Returns an object with a factory for each field defined on the type.
+* Factories are cached per schema+type to avoid recreation.
+*
+* @param schema - The GraphQL schema definition
+* @param typeName - The object type name to create factories for
+* @returns Object mapping field names to their selection factories
+*
+* @internal Used by operation and fragment composers
+*/
 const createFieldFactories = (schema, typeName) => {
 	const cacheMap = ensureCacheMapBySchema(schema);
 	const cached = cacheMap.get(typeName);
@@ -509,6 +558,15 @@ const evaluateSync = (executor, context) => {
 //#region packages/core/src/types/element/gql-element.ts
 const GQL_ELEMENT_FACTORY = Symbol("GQL_ELEMENT_FACTORY");
 const GQL_ELEMENT_CONTEXT = Symbol("GQL_ELEMENT_CONTEXT");
+/**
+* Abstract base class for all GraphQL elements (Fragment, Operation).
+*
+* Uses lazy evaluation with caching - definition is computed on first access.
+* Subclasses should not be instantiated directly; use static `create` methods.
+*
+* @template TDefinition - The shape of the evaluated definition
+* @template TInfer - Type inference metadata (access via `$infer`)
+*/
 var GqlElement = class GqlElement {
 	[GQL_ELEMENT_FACTORY];
 	[GQL_ELEMENT_CONTEXT] = null;
@@ -518,30 +576,55 @@ var GqlElement = class GqlElement {
 			throw new Error("This property is only for type meta. Do not access this property directly.");
 		} });
 	}
-	attach(attachment) {
-		let cache = null;
-		Object.defineProperty(this, attachment.name, { get() {
-			if (cache) return cache;
-			GqlElement.evaluateInstantly(this);
-			return cache = attachment.createValue(this);
-		} });
+	attach(attachmentOrAttachments) {
+		const attachments = Array.isArray(attachmentOrAttachments) ? attachmentOrAttachments : [attachmentOrAttachments];
+		for (const attachment of attachments) {
+			let cache = null;
+			const self = this;
+			Object.defineProperty(this, attachment.name, { get() {
+				if (cache) return cache;
+				GqlElement.evaluateInstantly(self);
+				return cache = attachment.createValue(self);
+			} });
+		}
 		return this;
 	}
+	/**
+	* Sets the canonical context for an element. Used by the builder.
+	* @internal
+	*/
 	static setContext(element, context) {
 		element[GQL_ELEMENT_CONTEXT] = context;
 	}
+	/**
+	* Gets the canonical context of an element, if set.
+	* @internal
+	*/
 	static getContext(element) {
 		return element[GQL_ELEMENT_CONTEXT];
 	}
+	/**
+	* Creates a generator for async evaluation. Used by the builder.
+	* @internal
+	*/
 	static createEvaluationGenerator(element) {
 		return createEvaluationGenerator(element[GQL_ELEMENT_FACTORY], element[GQL_ELEMENT_CONTEXT]);
 	}
 	static evaluateInstantly(element) {
 		return evaluateSync(element[GQL_ELEMENT_FACTORY], element[GQL_ELEMENT_CONTEXT]);
 	}
+	/**
+	* Forces synchronous evaluation. Throws if async operation is needed.
+	* @internal
+	*/
 	static evaluateSync(element) {
 		GqlElement.evaluateInstantly(element);
 	}
+	/**
+	* Evaluates and returns the element's definition.
+	* Throws if async operation is needed.
+	* @internal
+	*/
 	static get(element) {
 		return GqlElement.evaluateInstantly(element);
 	}
@@ -549,16 +632,37 @@ var GqlElement = class GqlElement {
 
 //#endregion
 //#region packages/core/src/types/element/fragment.ts
+/**
+* Represents a reusable GraphQL field selection on a specific type.
+*
+* Fragments are created via `gql(({ fragment }) => fragment.TypeName({ ... }))`.
+* Use `spread()` to include the fragment's fields in an operation.
+*
+* @template TTypeName - The GraphQL type this fragment selects from
+* @template TVariables - Variables required when spreading
+* @template TFields - The selected fields structure
+* @template TOutput - Inferred output type from selected fields
+*/
 var Fragment = class Fragment extends GqlElement {
 	constructor(define$1) {
 		super(define$1);
 	}
+	/** The GraphQL type name this fragment selects from. */
 	get typename() {
 		return GqlElement.get(this).typename;
 	}
+	/**
+	* Spreads this fragment's fields into a parent selection.
+	* Pass variables if the fragment defines any.
+	*/
 	get spread() {
 		return GqlElement.get(this).spread;
 	}
+	/**
+	* Creates a new Fragment instance.
+	* Prefer using the `gql(({ fragment }) => ...)` API instead.
+	* @internal
+	*/
 	static create(define$1) {
 		return new Fragment(define$1);
 	}
@@ -566,28 +670,55 @@ var Fragment = class Fragment extends GqlElement {
 
 //#endregion
 //#region packages/core/src/types/element/operation.ts
+/**
+* Represents a GraphQL operation (query, mutation, or subscription).
+*
+* Operations are created via `gql(({ query }) => query.operation({ ... }))`.
+* Produces a TypedDocumentNode for type-safe execution with GraphQL clients.
+*
+* @template TOperationType - 'query' | 'mutation' | 'subscription'
+* @template TOperationName - The unique operation name
+* @template TVariableNames - Tuple of variable names
+* @template TVariables - Variable types for the operation
+* @template TFields - Selected fields structure
+* @template TData - Inferred response data type
+*/
 var Operation = class Operation extends GqlElement {
 	constructor(define$1) {
 		super(define$1);
 	}
+	/** The operation type: 'query', 'mutation', or 'subscription'. */
 	get operationType() {
 		return GqlElement.get(this).operationType;
 	}
+	/** The unique name of this operation. */
 	get operationName() {
 		return GqlElement.get(this).operationName;
 	}
+	/** List of variable names defined for this operation. */
 	get variableNames() {
 		return GqlElement.get(this).variableNames;
 	}
+	/**
+	* Returns the field selections. Used for document reconstruction.
+	* @internal
+	*/
 	get documentSource() {
 		return GqlElement.get(this).documentSource;
 	}
+	/** The TypedDocumentNode for use with GraphQL clients. */
 	get document() {
 		return GqlElement.get(this).document;
 	}
+	/** Custom metadata attached to this operation, if any. */
 	get metadata() {
 		return GqlElement.get(this).metadata;
 	}
+	/**
+	* Creates a new Operation instance.
+	* Prefer using the `gql(({ query }) => ...)` API instead.
+	* @internal
+	*/
 	static create(define$1) {
 		return new Operation(define$1);
 	}
@@ -631,6 +762,21 @@ const recordFragmentUsage = (record) => {
 
 //#endregion
 //#region packages/core/src/composer/input.ts
+/**
+* Utilities for creating variable assignments and references.
+* @module
+*/
+/**
+* Creates variable assignments from provided values.
+*
+* Maps variable definitions to VarRefs. If a value is provided,
+* wraps it as a nested-value VarRef. If not provided, creates
+* an undefined VarRef (field will be omitted).
+*
+* Used when spreading fragments with partial variable values.
+*
+* @internal
+*/
 const createVarAssignments = (definitions, providedValues) => {
 	return mapValues(definitions, (_, key) => {
 		const varName = key;
@@ -640,10 +786,34 @@ const createVarAssignments = (definitions, providedValues) => {
 		return createVarRefFromNestedValue(provided);
 	});
 };
+/**
+* Creates variable references from variable definitions.
+*
+* Maps each variable definition to a VarRef pointing to that variable.
+* Used in operation builders to create the `$` context object.
+*
+* @internal
+*/
 const createVarRefs = (definitions) => mapValues(definitions, (_, name) => createVarRefFromVariable(name));
 
 //#endregion
 //#region packages/core/src/composer/fragment.ts
+/**
+* Fragment composer factory for creating reusable field selections.
+* @module
+*/
+/**
+* Creates fragment builder functions for all object types in the schema.
+*
+* Returns an object with a builder for each type (e.g., `fragment.User`, `fragment.Post`).
+* Each builder creates a `Fragment` that can be spread into operations.
+*
+* @param schema - The GraphQL schema definition
+* @param _adapter - Optional metadata adapter (for fragment metadata)
+* @returns Object mapping type names to fragment builder functions
+*
+* @internal Used by `createGqlElementComposer`
+*/
 const createGqlFragmentComposers = (schema, _adapter) => {
 	const createFragmentComposer = (typename) => {
 		return (options) => {
@@ -683,6 +853,25 @@ const defaultMetadataAdapter = createDefaultAdapter();
 
 //#endregion
 //#region packages/core/src/composer/operation.ts
+/**
+* Operation composer factory for creating typed GraphQL operations.
+* @module
+*/
+/**
+* Creates a factory for composing GraphQL operations.
+*
+* Returns a curried function: first select operation type (query/mutation/subscription),
+* then define the operation with name, variables, and fields.
+*
+* Handles metadata aggregation from fragments (sync or async) and builds
+* the TypedDocumentNode automatically.
+*
+* @param schema - The GraphQL schema definition
+* @param adapter - Optional metadata adapter for custom metadata handling
+* @returns Operation type selector function
+*
+* @internal Used by `createGqlElementComposer`
+*/
 const createOperationComposerFactory = (schema, adapter) => {
 	const resolvedAdapter = adapter ?? defaultMetadataAdapter;
 	return (operationType) => {
@@ -744,7 +933,9 @@ const createOperationComposerFactory = (schema, adapter) => {
 //#region packages/core/src/composer/var-ref-tools.ts
 /**
 * Recursively checks if a NestedValue contains any VarRef.
+*
 * Used by getVarRefValue to determine if it's safe to return as ConstValue.
+* @internal
 */
 const hasVarRefInside = (value) => {
 	if (value instanceof VarRef) return true;
@@ -856,6 +1047,18 @@ const getValueAt = (varRef, selector) => {
 	if (hasVarRefInside(inner.varInner.value)) throw new Error(`Value at path [${inner.segments.join(".")}] contains nested VarRef`);
 	return inner.varInner.value;
 };
+/**
+* Gets the full path to a variable within a nested structure.
+*
+* Returns path segments starting with `$variableName` followed by
+* property accesses within that variable's value.
+*
+* @example
+* ```typescript
+* getVariablePath($.filter, p => p.user.id)
+* // Returns: ["$filter", "user", "id"]
+* ```
+*/
 const getVariablePath = (varRef, selector) => {
 	const inner = getSelectableProxyInner(selector(createSelectableProxy({
 		varInner: VarRef.getInner(varRef),
@@ -908,7 +1111,16 @@ const createVarMethodFactory = () => {
 	};
 };
 /**
-* Creates a variable builder that uses injected input type methods.
+* Creates a variable builder using injected input type methods.
+*
+* The returned builder provides type-safe variable definition methods
+* for all input types in the schema. Also includes utilities for
+* extracting variable names and values from VarRefs.
+*
+* @param inputTypeMethods - Methods for each input type (from codegen)
+* @returns Variable builder with methods for all input types
+*
+* @internal Used by `createGqlElementComposer`
 */
 const createVarBuilder = (inputTypeMethods) => {
 	const varBuilder = (varName) => {
@@ -933,9 +1145,29 @@ const createVarBuilder = (inputTypeMethods) => {
 /**
 * Creates a GQL element composer for a given schema.
 *
-* @typeParam TSchema - The GraphQL schema type
-* @typeParam TAdapter - The adapter type (optional)
-* @typeParam TFragmentBuilders - Pre-computed fragment builders type (optional, for codegen optimization)
+* This is the main entry point for defining GraphQL operations and fragments.
+* The returned function provides a context with:
+* - `fragment`: Builders for each object type
+* - `query/mutation/subscription`: Operation builders
+* - `$var`: Variable definition helpers
+* - `$colocate`: Fragment colocation utilities
+*
+* @param schema - The GraphQL schema definition
+* @param options - Configuration including input type methods and optional adapter
+* @returns Element composer function
+*
+* @example
+* ```typescript
+* const gql = createGqlElementComposer(schema, { inputTypeMethods });
+*
+* const GetUser = gql(({ query, $var }) =>
+*   query.operation({
+*     name: "GetUser",
+*     variables: { id: $var.ID("!") },
+*     fields: ({ f, $ }) => ({ ...f.user({ id: $.id })(...) }),
+*   })
+* );
+* ```
 */
 const createGqlElementComposer = (schema, options) => {
 	const { adapter, inputTypeMethods } = options;