@soda-gql/core 0.11.10 → 0.11.12

package/dist/index.cjs

@@ -454,541 +454,652 @@ const createColocateHelper = () => {
 };
 
 //#endregion
-//#region packages/core/src/composer/directive-builder.ts
+//#region packages/core/src/utils/promise.ts
 /**
-* Directive builder utilities for creating field-level directives.
-*
-* Provides type-safe methods for creating directive references that can be
-* applied to field selections. The builder follows a similar pattern to
-* the variable builder ($var).
-*
+* Promise detection utilities for cross-realm compatibility.
 * @module
 */
 /**
-* Creates a directive method factory for a specific directive.
+* Check if a value is Promise-like (has .then method).
 *
-* @param name - The directive name (without @)
-* @param locations - Valid locations where the directive can be applied
-* @returns A function that creates DirectiveRef instances
+* This function uses duck typing instead of `instanceof Promise` to work across
+* VM sandbox boundaries where Promises created in a different realm have a
+* different constructor.
 *
 * @example
 * ```typescript
-* const skipMethod = createDirectiveMethod("skip", ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"] as const);
-* const skipDirective = skipMethod({ if: true });
-* ```
-*/
-const createDirectiveMethod = (name, locations) => {
-	return (args) => new DirectiveRef({
-		name,
-		arguments: args,
-		locations
-	});
-};
-/**
-* Creates a typed directive method with argument type specifiers.
-* Enables enum value output in directive arguments.
+* // Works with native Promises
+* isPromiseLike(Promise.resolve(42)); // true
 *
-* @param name - The directive name (without @)
-* @param locations - Valid locations where the directive can be applied
-* @param argSpecs - Type specifiers for directive arguments
-* @returns A function that creates DirectiveRef instances with argument type info
+* // Works with VM sandbox Promises (instanceof would fail)
+* const vmPromise = vm.runInContext("Promise.resolve(42)", context);
+* isPromiseLike(vmPromise); // true (instanceof Promise would be false)
 *
-* @example
-* ```typescript
-* const authMethod = createTypedDirectiveMethod(
-*   "auth",
-*   ["FIELD"] as const,
-*   { role: { kind: "enum", name: "Role", modifier: "!" } }
-* );
-* const authDirective = authMethod({ role: "ADMIN" });
+* // Rejects non-Promises
+* isPromiseLike({ then: "not a function" }); // false
+* isPromiseLike(null); // false
+* isPromiseLike(42); // false
 * ```
 */
-const createTypedDirectiveMethod = (name, locations, argSpecs) => {
-	return (args) => new DirectiveRef({
-		name,
-		arguments: args,
-		locations,
-		argumentSpecs: argSpecs
-	});
+const isPromiseLike = (value) => {
+	return value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
 };
+
+//#endregion
+//#region packages/core/src/types/element/lazy-evaluator.ts
 /**
-* Standard directive locations for @skip and @include.
+* Creates a lazy evaluator with caching, async support, and dependency ordering.
+*
+* @param define - Factory function that produces the value
+* @param getDeps - Optional function returning dependencies to evaluate first
+* @param createDepGenerator - Function to create evaluation generator for a dependency
+* @returns An executor generator function
 */
-const CONDITIONAL_DIRECTIVE_LOCATIONS = [
-	"FIELD",
-	"FRAGMENT_SPREAD",
-	"INLINE_FRAGMENT"
-];
+const createLazyEvaluator = (define, getDeps, createDepGenerator) => {
+	let cache = null;
+	let promise = null;
+	return function* execute(context) {
+		if (cache) return cache.value;
+		if (promise) {
+			yield promise;
+			return cache.value;
+		}
+		if (getDeps) for (const dep of getDeps()) yield* createDepGenerator(dep);
+		const defined = define(context);
+		if (!isPromiseLike(defined)) return (cache = { value: defined }).value;
+		promise = defined.then((value) => {
+			cache = { value };
+			promise = null;
+		});
+		yield promise;
+		return cache.value;
+	};
+};
 /**
-* Creates the standard GraphQL directives (@skip, @include).
-* These are always available regardless of schema definition.
-*
-* @returns Object containing skip and include directive methods
-*
-* @example
-* ```typescript
-* const $dir = createStandardDirectives();
-* const skipDirective = $dir.skip({ if: true });
-* ```
+* Creates an evaluation generator from an executor.
+* Wraps the executor's generator and discards its return value.
 */
-const createStandardDirectives = () => ({
-	skip: createDirectiveMethod("skip", CONDITIONAL_DIRECTIVE_LOCATIONS),
-	include: createDirectiveMethod("include", CONDITIONAL_DIRECTIVE_LOCATIONS)
-});
+function* createEvaluationGenerator(executor, context) {
+	yield* executor(context);
+}
 /**
-* Creates a directive builder with standard directives and optional custom directives.
-*
-* @param customDirectives - Additional directive methods from schema (generated by codegen)
-* @returns Combined directive builder with all available directives
-*
-* @internal Used by codegen to create schema-specific directive builders
+* Executes the evaluator synchronously.
+* Throws if async operation is encountered.
 */
-const createDirectiveBuilder = (customDirectives) => {
-	return {
-		...createStandardDirectives(),
-		...customDirectives ?? {}
-	};
+const evaluateSync = (executor, context) => {
+	const result = executor(context).next();
+	if (!result.done) throw new Error("Async operation is not supported in sync evaluation.");
+	return result.value;
 };
+
+//#endregion
+//#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");
 /**
-* Type guard to check if a value is a DirectiveRef.
+* Abstract base class for all GraphQL elements (Fragment, Operation).
 *
-* @param value - Value to check
-* @returns True if value is a DirectiveRef instance
+* 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`)
 */
-const isDirectiveRef = (value) => {
-	return value instanceof DirectiveRef;
+var GqlElement = class GqlElement {
+	[GQL_ELEMENT_FACTORY];
+	[GQL_ELEMENT_CONTEXT] = null;
+	constructor(define, getDeps) {
+		this[GQL_ELEMENT_FACTORY] = createLazyEvaluator(define, getDeps, GqlElement.createEvaluationGenerator);
+		Object.defineProperty(this, "$infer", { get() {
+			throw new Error("This property is only for type meta. Do not access this property directly.");
+		} });
+	}
+	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);
+	}
 };
 
 //#endregion
-//#region packages/core/src/composer/field-path-context.ts
+//#region packages/core/src/types/element/define.ts
 /**
-* Shared mutable container for field path context.
-* Only synchronous access is supported.
+* Define element for storing arbitrary value factories.
+* @module
 */
-const fieldPathContext = { current: null };
 /**
-* Get the current field path.
-* Returns null if not in a field building context.
+* Represents a factory-based value definition.
+*
+* Define elements are created via `gql(({ define }) => define(() => value))`.
+* The factory is evaluated lazily and the result is cached.
+*
+* @template TValue - The type of value produced by the factory
 *
 * @example
 * ```typescript
-* import { getCurrentFieldPath } from '@soda-gql/core';
-*
-* // Inside a field builder or model spread:
-* const path = getCurrentFieldPath();
-* console.log(path?.full); // "$.user.posts[].author"
+* // Store a primitive value
+* const myNumber = gql.default(({ define }) => define(() => 42));
+* console.log(myNumber.value); // 42
+*
+* // Store a plain object
+* const myConfig = gql.default(({ define }) => define(() => ({
+*   apiUrl: "https://api.example.com",
+*   timeout: 5000,
+* })));
+* console.log(myConfig.value.apiUrl); // "https://api.example.com"
 * ```
 */
-const getCurrentFieldPath = () => fieldPathContext.current;
-/**
-* Run a function with a specific field path context.
-* Restores the previous path after the function completes.
-*
-* @internal
-*/
-const withFieldPath = (path, fn) => {
-	const previousPath = fieldPathContext.current;
-	fieldPathContext.current = path;
-	try {
-		return fn();
-	} finally {
-		fieldPathContext.current = previousPath;
+var GqlDefine = class GqlDefine extends GqlElement {
+	constructor(define) {
+		super(define);
+	}
+	/**
+	* The evaluated value from the factory.
+	* Triggers lazy evaluation on first access.
+	*/
+	get value() {
+		return GqlElement.get(this).factoryResult;
+	}
+	/**
+	* Creates a new GqlDefine instance.
+	*
+	* Prefer using the `gql(({ define }) => define(() => value))` API instead.
+	*
+	* @param factory - Function that produces the value. Can be sync or async.
+	* @returns A new GqlDefine instance wrapping the factory result.
+	*
+	* @example
+	* ```typescript
+	* // Sync factory
+	* const syncDefine = GqlDefine.create(() => 42);
+	*
+	* // Async factory
+	* const asyncDefine = GqlDefine.create(async () => {
+	*   const data = await fetch('/api/config');
+	*   return data.json();
+	* });
+	* ```
+	*/
+	static create(factory) {
+		return new GqlDefine((_context) => {
+			const result = factory();
+			if (isPromiseLike(result)) return result.then((value) => ({ factoryResult: value }));
+			return { factoryResult: result };
+		});
 	}
 };
+
+//#endregion
+//#region packages/core/src/types/element/fragment.ts
 /**
-* Append a new segment to the current path.
+* Represents a reusable GraphQL field selection on a specific type.
 *
-* @internal
+* 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
 */
-const appendToPath = (parent, segment) => {
-	const listSuffix = segment.isList ? "[]" : "";
-	const newSegment = {
-		field: segment.field,
-		parent: segment.parentType,
-		isList: segment.isList
-	};
-	if (!parent) return {
-		full: `$.${segment.field}${listSuffix}`,
-		segments: [newSegment]
-	};
-	return {
-		full: `${parent.full}.${segment.field}${listSuffix}`,
-		segments: [...parent.segments, newSegment]
-	};
+var Fragment = class Fragment extends GqlElement {
+	constructor(define) {
+		super(define);
+	}
+	/** The GraphQL type name this fragment selects from. */
+	get typename() {
+		return GqlElement.get(this).typename;
+	}
+	/** Optional unique key for prebuilt type lookup. */
+	get key() {
+		return GqlElement.get(this).key;
+	}
+	/** The schema label this fragment belongs to. */
+	get schemaLabel() {
+		return GqlElement.get(this).schemaLabel;
+	}
+	/** Variable definitions for this fragment. */
+	get variableDefinitions() {
+		return GqlElement.get(this).variableDefinitions;
+	}
+	/**
+	* 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) {
+		return new Fragment(define);
+	}
 };
+
+//#endregion
+//#region packages/core/src/types/element/operation.ts
 /**
-* Check if a type specifier represents a list type.
-* Matches patterns like "Type:![]!", "Type:![]?", "Type:?[]!", etc.
+* Represents a GraphQL operation (query, mutation, or subscription).
 *
-* @internal
+* 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
 */
-const isListType = (typeString) => {
-	return typeString.includes("[]");
+var Operation = class Operation extends GqlElement {
+	constructor(define) {
+		super(define);
+	}
+	/** 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;
+	}
+	/** The schema label this operation belongs to. */
+	get schemaLabel() {
+		return GqlElement.get(this).schemaLabel;
+	}
+	/** 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) {
+		return new Operation(define);
+	}
 };
 
 //#endregion
-//#region packages/core/src/utils/map-values.ts
-function mapValues(obj, fn) {
-	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value, key)]));
-}
-
-//#endregion
-//#region packages/core/src/composer/fields-builder.ts
-const cacheMapBySchema = /* @__PURE__ */ new WeakMap();
-const ensureCacheMapBySchema = (schema) => {
-	const cachedCacheMap = cacheMapBySchema.get(schema);
-	if (cachedCacheMap) return cachedCacheMap;
-	const cacheMap = /* @__PURE__ */ new Map();
-	cacheMapBySchema.set(schema, cacheMap);
-	return cacheMap;
-};
+//#region packages/core/src/composer/compat.ts
 /**
-* Creates field selection factories for a given object type.
+* Compat composer factory for creating GraphQL operation specifications.
+* @module
+*/
+/**
+* Creates a factory for composing compat operation specifications.
 *
-* Returns an object with a factory for each field defined on the type.
-* Factories are cached per schema+type to avoid recreation.
+* Returns a function that creates a `GqlDefine<CompatSpec<...>>` storing
+* the operation specification with unevaluated fieldsBuilder.
 *
 * @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
+* @param operationType - The operation type ('query' | 'mutation' | 'subscription')
+* @returns Compat operation composer function
 *
-* @internal Used by operation and fragment composers
+* @internal Used by `createGqlElementComposer`
 */
-const createFieldFactories = (schema, typeName) => {
-	const cacheMap = ensureCacheMapBySchema(schema);
-	const cached = cacheMap.get(typeName);
-	if (cached) return cached;
-	const factories = createFieldFactoriesInner(schema, typeName);
-	cacheMap.set(typeName, factories);
-	return factories;
-};
-const createFieldFactoriesInner = (schema, typeName) => {
-	const typeDef = schema.object[typeName];
-	if (!typeDef) throw new Error(`Type ${typeName} is not defined in schema objects`);
-	const entries = Object.entries(typeDef.fields).map(([fieldName, type]) => {
-		const factory = (fieldArgs, extras) => {
-			const wrap = (value) => require_schema_builder.wrapByKey(extras?.alias ?? fieldName, value);
-			const directives = extras?.directives ?? [];
-			if (type.kind === "object") {
-				const factoryReturn = ((nest) => {
-					const nestedFields = withFieldPath(appendToPath(getCurrentFieldPath(), {
-						field: fieldName,
-						parentType: typeName,
-						isList: isListType(type.modifier)
-					}), () => nest({ f: createFieldFactories(schema, type.name) }));
-					return wrap({
-						parent: typeName,
-						field: fieldName,
-						type,
-						args: fieldArgs ?? {},
-						directives,
-						object: nestedFields,
-						union: null
-					});
-				});
-				return factoryReturn;
-			}
-			if (type.kind === "union") {
-				const factoryReturn = ((nest) => {
-					const nestedUnion = withFieldPath(appendToPath(getCurrentFieldPath(), {
-						field: fieldName,
-						parentType: typeName,
-						isList: isListType(type.modifier)
-					}), () => mapValues(nest, (builder, memberName) => {
-						if (!builder) throw new Error(`Builder is undefined for member name: ${memberName}`);
-						return builder({ f: createFieldFactories(schema, memberName) });
-					}));
-					return wrap({
-						parent: typeName,
-						field: fieldName,
-						type,
-						args: fieldArgs ?? {},
-						directives,
-						object: null,
-						union: nestedUnion
-					});
-				});
-				return factoryReturn;
-			}
-			if (type.kind === "scalar" || type.kind === "enum" || type.kind === "typename") return wrap({
-				parent: typeName,
-				field: fieldName,
-				type,
-				args: fieldArgs ?? {},
-				directives,
-				object: null,
-				union: null
-			});
-			throw new Error(`Unsupported field type: ${type}`);
-		};
-		return [fieldName, factory];
-	});
-	return Object.fromEntries(entries);
+const createCompatComposer = (schema, operationType) => {
+	if (schema.operations[operationType] === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
+	return (options) => {
+		return GqlDefine.create(() => ({
+			schema,
+			operationType,
+			operationName: options.name,
+			variables: options.variables ?? {},
+			fieldsBuilder: options.fields
+		}));
+	};
 };
 
 //#endregion
-//#region packages/core/src/utils/promise.ts
+//#region packages/core/src/composer/directive-builder.ts
 /**
-* Promise detection utilities for cross-realm compatibility.
+* Directive builder utilities for creating field-level directives.
+*
+* Provides type-safe methods for creating directive references that can be
+* applied to field selections. The builder follows a similar pattern to
+* the variable builder ($var).
+*
 * @module
 */
 /**
-* Check if a value is Promise-like (has .then method).
+* Creates a directive method factory for a specific directive.
 *
-* This function uses duck typing instead of `instanceof Promise` to work across
-* VM sandbox boundaries where Promises created in a different realm have a
-* different constructor.
+* @param name - The directive name (without @)
+* @param locations - Valid locations where the directive can be applied
+* @returns A function that creates DirectiveRef instances
 *
 * @example
 * ```typescript
-* // Works with native Promises
-* isPromiseLike(Promise.resolve(42)); // true
+* const skipMethod = createDirectiveMethod("skip", ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"] as const);
+* const skipDirective = skipMethod({ if: true });
+* ```
+*/
+const createDirectiveMethod = (name, locations) => {
+	return (args) => new DirectiveRef({
+		name,
+		arguments: args,
+		locations
+	});
+};
+/**
+* Creates a typed directive method with argument type specifiers.
+* Enables enum value output in directive arguments.
 *
-* // Works with VM sandbox Promises (instanceof would fail)
-* const vmPromise = vm.runInContext("Promise.resolve(42)", context);
-* isPromiseLike(vmPromise); // true (instanceof Promise would be false)
+* @param name - The directive name (without @)
+* @param locations - Valid locations where the directive can be applied
+* @param argSpecs - Type specifiers for directive arguments
+* @returns A function that creates DirectiveRef instances with argument type info
 *
-* // Rejects non-Promises
-* isPromiseLike({ then: "not a function" }); // false
-* isPromiseLike(null); // false
-* isPromiseLike(42); // false
+* @example
+* ```typescript
+* const authMethod = createTypedDirectiveMethod(
+*   "auth",
+*   ["FIELD"] as const,
+*   { role: { kind: "enum", name: "Role", modifier: "!" } }
+* );
+* const authDirective = authMethod({ role: "ADMIN" });
 * ```
 */
-const isPromiseLike = (value) => {
-	return value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
+const createTypedDirectiveMethod = (name, locations, argSpecs) => {
+	return (args) => new DirectiveRef({
+		name,
+		arguments: args,
+		locations,
+		argumentSpecs: argSpecs
+	});
 };
-
-//#endregion
-//#region packages/core/src/types/element/lazy-evaluator.ts
 /**
-* Creates a lazy evaluator with caching, async support, and dependency ordering.
+* Standard directive locations for @skip and @include.
+*/
+const CONDITIONAL_DIRECTIVE_LOCATIONS = [
+	"FIELD",
+	"FRAGMENT_SPREAD",
+	"INLINE_FRAGMENT"
+];
+/**
+* Creates the standard GraphQL directives (@skip, @include).
+* These are always available regardless of schema definition.
 *
-* @param define - Factory function that produces the value
-* @param getDeps - Optional function returning dependencies to evaluate first
-* @param createDepGenerator - Function to create evaluation generator for a dependency
-* @returns An executor generator function
+* @returns Object containing skip and include directive methods
+*
+* @example
+* ```typescript
+* const $dir = createStandardDirectives();
+* const skipDirective = $dir.skip({ if: true });
+* ```
 */
-const createLazyEvaluator = (define, getDeps, createDepGenerator) => {
-	let cache = null;
-	let promise = null;
-	return function* execute(context) {
-		if (cache) return cache.value;
-		if (promise) {
-			yield promise;
-			return cache.value;
-		}
-		if (getDeps) for (const dep of getDeps()) yield* createDepGenerator(dep);
-		const defined = define(context);
-		if (!isPromiseLike(defined)) return (cache = { value: defined }).value;
-		promise = defined.then((value) => {
-			cache = { value };
-			promise = null;
-		});
-		yield promise;
-		return cache.value;
+const createStandardDirectives = () => ({
+	skip: createDirectiveMethod("skip", CONDITIONAL_DIRECTIVE_LOCATIONS),
+	include: createDirectiveMethod("include", CONDITIONAL_DIRECTIVE_LOCATIONS)
+});
+/**
+* Creates a directive builder with standard directives and optional custom directives.
+*
+* @param customDirectives - Additional directive methods from schema (generated by codegen)
+* @returns Combined directive builder with all available directives
+*
+* @internal Used by codegen to create schema-specific directive builders
+*/
+const createDirectiveBuilder = (customDirectives) => {
+	return {
+		...createStandardDirectives(),
+		...customDirectives ?? {}
 	};
 };
 /**
-* Creates an evaluation generator from an executor.
-* Wraps the executor's generator and discards its return value.
+* Type guard to check if a value is a DirectiveRef.
+*
+* @param value - Value to check
+* @returns True if value is a DirectiveRef instance
 */
-function* createEvaluationGenerator(executor, context) {
-	yield* executor(context);
-}
+const isDirectiveRef = (value) => {
+	return value instanceof DirectiveRef;
+};
+
+//#endregion
+//#region packages/core/src/types/metadata/adapter.ts
 /**
-* Executes the evaluator synchronously.
-* Throws if async operation is encountered.
+* Creates the default adapter instance.
+* @internal
 */
-const evaluateSync = (executor, context) => {
-	const result = executor(context).next();
-	if (!result.done) throw new Error("Async operation is not supported in sync evaluation.");
-	return result.value;
-};
+const createDefaultAdapter = () => ({ aggregateFragmentMetadata: (fragments) => fragments.map((m) => m.metadata) });
+/**
+* The default adapter instance.
+*/
+const defaultMetadataAdapter = createDefaultAdapter();
 
 //#endregion
-//#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");
+//#region packages/core/src/utils/map-values.ts
+function mapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value, key)]));
+}
+
+//#endregion
+//#region packages/core/src/composer/field-path-context.ts
 /**
-* Abstract base class for all GraphQL elements (Fragment, Operation).
+* Shared mutable container for field path context.
+* Only synchronous access is supported.
+*/
+const fieldPathContext = { current: null };
+/**
+* Get the current field path.
+* Returns null if not in a field building context.
 *
-* Uses lazy evaluation with caching - definition is computed on first access.
-* Subclasses should not be instantiated directly; use static `create` methods.
+* @example
+* ```typescript
+* import { getCurrentFieldPath } from '@soda-gql/core';
 *
-* @template TDefinition - The shape of the evaluated definition
-* @template TInfer - Type inference metadata (access via `$infer`)
+* // Inside a field builder or model spread:
+* const path = getCurrentFieldPath();
+* console.log(path?.full); // "$.user.posts[].author"
+* ```
 */
-var GqlElement = class GqlElement {
-	[GQL_ELEMENT_FACTORY];
-	[GQL_ELEMENT_CONTEXT] = null;
-	constructor(define, getDeps) {
-		this[GQL_ELEMENT_FACTORY] = createLazyEvaluator(define, getDeps, GqlElement.createEvaluationGenerator);
-		Object.defineProperty(this, "$infer", { get() {
-			throw new Error("This property is only for type meta. Do not access this property directly.");
-		} });
-	}
-	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);
+const getCurrentFieldPath = () => fieldPathContext.current;
+/**
+* Run a function with a specific field path context.
+* Restores the previous path after the function completes.
+*
+* @internal
+*/
+const withFieldPath = (path, fn) => {
+	const previousPath = fieldPathContext.current;
+	fieldPathContext.current = path;
+	try {
+		return fn();
+	} finally {
+		fieldPathContext.current = previousPath;
 	}
 };
-
-//#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.
+* Append a new segment to the current path.
+*
+* @internal
+*/
+const appendToPath = (parent, segment) => {
+	const listSuffix = segment.isList ? "[]" : "";
+	const newSegment = {
+		field: segment.field,
+		parent: segment.parentType,
+		isList: segment.isList
+	};
+	if (!parent) return {
+		full: `$.${segment.field}${listSuffix}`,
+		segments: [newSegment]
+	};
+	return {
+		full: `${parent.full}.${segment.field}${listSuffix}`,
+		segments: [...parent.segments, newSegment]
+	};
+};
+/**
+* Check if a type specifier represents a list type.
+* Matches patterns like "Type:![]!", "Type:![]?", "Type:?[]!", etc.
 *
-* @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
+* @internal
 */
-var Fragment = class Fragment extends GqlElement {
-	constructor(define) {
-		super(define);
-	}
-	/** The GraphQL type name this fragment selects from. */
-	get typename() {
-		return GqlElement.get(this).typename;
-	}
-	/** Optional unique key for prebuilt type lookup. */
-	get key() {
-		return GqlElement.get(this).key;
-	}
-	/** The schema label this fragment belongs to. */
-	get schemaLabel() {
-		return GqlElement.get(this).schemaLabel;
-	}
-	/** Variable definitions for this fragment. */
-	get variableDefinitions() {
-		return GqlElement.get(this).variableDefinitions;
-	}
-	/**
-	* 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) {
-		return new Fragment(define);
-	}
+const isListType = (typeString) => {
+	return typeString.includes("[]");
 };
 
 //#endregion
-//#region packages/core/src/types/element/operation.ts
+//#region packages/core/src/composer/fields-builder.ts
+const cacheMapBySchema = /* @__PURE__ */ new WeakMap();
+const ensureCacheMapBySchema = (schema) => {
+	const cachedCacheMap = cacheMapBySchema.get(schema);
+	if (cachedCacheMap) return cachedCacheMap;
+	const cacheMap = /* @__PURE__ */ new Map();
+	cacheMapBySchema.set(schema, cacheMap);
+	return cacheMap;
+};
 /**
-* Represents a GraphQL operation (query, mutation, or subscription).
+* Creates field selection factories for a given object type.
 *
-* Operations are created via `gql(({ query }) => query.operation({ ... }))`.
-* Produces a TypedDocumentNode for type-safe execution with GraphQL clients.
+* Returns an object with a factory for each field defined on the type.
+* Factories are cached per schema+type to avoid recreation.
 *
-* @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
+* @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
 */
-var Operation = class Operation extends GqlElement {
-	constructor(define) {
-		super(define);
-	}
-	/** 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;
-	}
-	/** The schema label this operation belongs to. */
-	get schemaLabel() {
-		return GqlElement.get(this).schemaLabel;
-	}
-	/** 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) {
-		return new Operation(define);
-	}
+const createFieldFactories = (schema, typeName) => {
+	const cacheMap = ensureCacheMapBySchema(schema);
+	const cached = cacheMap.get(typeName);
+	if (cached) return cached;
+	const factories = createFieldFactoriesInner(schema, typeName);
+	cacheMap.set(typeName, factories);
+	return factories;
+};
+const createFieldFactoriesInner = (schema, typeName) => {
+	const typeDef = schema.object[typeName];
+	if (!typeDef) throw new Error(`Type ${typeName} is not defined in schema objects`);
+	const entries = Object.entries(typeDef.fields).map(([fieldName, type]) => {
+		const factory = (fieldArgs, extras) => {
+			const wrap = (value) => require_schema_builder.wrapByKey(extras?.alias ?? fieldName, value);
+			const directives = extras?.directives ?? [];
+			if (type.kind === "object") {
+				const factoryReturn = ((nest) => {
+					const nestedFields = withFieldPath(appendToPath(getCurrentFieldPath(), {
+						field: fieldName,
+						parentType: typeName,
+						isList: isListType(type.modifier)
+					}), () => nest({ f: createFieldFactories(schema, type.name) }));
+					return wrap({
+						parent: typeName,
+						field: fieldName,
+						type,
+						args: fieldArgs ?? {},
+						directives,
+						object: nestedFields,
+						union: null
+					});
+				});
+				return factoryReturn;
+			}
+			if (type.kind === "union") {
+				const factoryReturn = ((nest) => {
+					const nestedUnion = withFieldPath(appendToPath(getCurrentFieldPath(), {
+						field: fieldName,
+						parentType: typeName,
+						isList: isListType(type.modifier)
+					}), () => mapValues(nest, (builder, memberName) => {
+						if (!builder) throw new Error(`Builder is undefined for member name: ${memberName}`);
+						return builder({ f: createFieldFactories(schema, memberName) });
+					}));
+					return wrap({
+						parent: typeName,
+						field: fieldName,
+						type,
+						args: fieldArgs ?? {},
+						directives,
+						object: null,
+						union: nestedUnion
+					});
+				});
+				return factoryReturn;
+			}
+			if (type.kind === "scalar" || type.kind === "enum" || type.kind === "typename") return wrap({
+				parent: typeName,
+				field: fieldName,
+				type,
+				args: fieldArgs ?? {},
+				directives,
+				object: null,
+				union: null
+			});
+			throw new Error(`Unsupported field type: ${type}`);
+		};
+		return [fieldName, factory];
+	});
+	return Object.fromEntries(entries);
 };
 
 //#endregion
@@ -1063,6 +1174,142 @@ const createVarAssignments = (definitions, providedValues) => {
 */
 const createVarRefs = (definitions) => mapValues(definitions, (_, name) => createVarRefFromVariable(name));
 
+//#endregion
+//#region packages/core/src/composer/operation-core.ts
+/**
+* Builds an operation artifact from the provided parameters.
+*
+* This function contains the core logic for:
+* - Creating variable refs and field factories
+* - Evaluating fields with fragment usage tracking
+* - Building the document
+* - Handling metadata (sync and async)
+* - Applying document transformations
+*
+* @param params - Operation building parameters
+* @returns Operation artifact or Promise of artifact (if async metadata)
+*
+* @internal Used by operation.ts and extend.ts
+*/
+const buildOperationArtifact = (params) => {
+	const { schema, operationType, operationTypeName, operationName, variables, fieldsFactory, adapter, metadata: metadataBuilder, transformDocument: operationTransformDocument, adapterTransformDocument } = params;
+	const $ = createVarRefs(variables);
+	const f = createFieldFactories(schema, operationTypeName);
+	const { result: fields, usages: fragmentUsages } = withFragmentUsageCollection(() => fieldsFactory({
+		f,
+		$
+	}));
+	const document = buildDocument({
+		operationName,
+		operationType,
+		variables,
+		fields,
+		schema
+	});
+	const variableNames = Object.keys(variables);
+	if (!fragmentUsages.some((u) => u.metadataBuilder) && !metadataBuilder && !adapterTransformDocument && !operationTransformDocument) return {
+		operationType,
+		operationName,
+		schemaLabel: schema.label,
+		variableNames,
+		documentSource: () => fields,
+		document,
+		metadata: void 0
+	};
+	const aggregateFragmentMetadata = (resolvedFragmentMetadata) => {
+		const fragmentMetaInfos = fragmentUsages.map((usage, index) => ({
+			metadata: resolvedFragmentMetadata[index],
+			fieldPath: usage.path
+		}));
+		return adapter.aggregateFragmentMetadata(fragmentMetaInfos);
+	};
+	const fragmentMetadataResults = fragmentUsages.map((usage) => usage.metadataBuilder ? usage.metadataBuilder() : void 0);
+	const hasAsyncFragmentMetadata = fragmentMetadataResults.some((r) => isPromiseLike(r));
+	const buildOperationMetadata = (aggregatedFragmentMetadata) => {
+		const schemaLevel = adapter.schemaLevel;
+		return metadataBuilder?.({
+			$,
+			document,
+			fragmentMetadata: aggregatedFragmentMetadata,
+			schemaLevel
+		});
+	};
+	const makeCreateArtifact = (aggregated$1) => {
+		return ({ metadata }) => {
+			let finalDocument = operationTransformDocument ? operationTransformDocument({
+				document,
+				metadata
+			}) : document;
+			if (adapterTransformDocument) finalDocument = adapterTransformDocument({
+				document: finalDocument,
+				operationName,
+				operationType,
+				variableNames,
+				schemaLevel: adapter.schemaLevel,
+				fragmentMetadata: aggregated$1
+			});
+			return {
+				operationType,
+				operationName,
+				schemaLabel: schema.label,
+				variableNames,
+				documentSource: () => fields,
+				document: finalDocument,
+				metadata
+			};
+		};
+	};
+	if (hasAsyncFragmentMetadata) return Promise.all(fragmentMetadataResults).then(async (resolvedFragmentMetadata) => {
+		const aggregated$1 = aggregateFragmentMetadata(resolvedFragmentMetadata);
+		const operationMetadata = await buildOperationMetadata(aggregated$1);
+		return makeCreateArtifact(aggregated$1)({ metadata: operationMetadata });
+	});
+	const aggregated = aggregateFragmentMetadata(fragmentMetadataResults);
+	const createArtifact = makeCreateArtifact(aggregated);
+	const operationMetadataResult = buildOperationMetadata(aggregated);
+	if (isPromiseLike(operationMetadataResult)) return operationMetadataResult.then((metadata) => createArtifact({ metadata }));
+	return createArtifact({ metadata: operationMetadataResult });
+};
+
+//#endregion
+//#region packages/core/src/composer/extend.ts
+/**
+* Extend composer factory for creating Operations from compat specs.
+* @module
+*/
+/**
+* Creates a factory for extending compat specs into full operations.
+*
+* The extend function takes a compat spec (created by `query.compat()`) and
+* optional metadata/transformDocument options, then creates a full Operation.
+*
+* @param schema - The GraphQL schema definition
+* @param adapter - Optional metadata adapter for custom metadata handling
+* @param transformDocument - Optional document transformer
+* @returns Extend composer function
+*
+* @internal Used by `createGqlElementComposer`
+*/
+const createExtendComposer = (schema, adapter, transformDocument) => {
+	const resolvedAdapter = adapter ?? defaultMetadataAdapter;
+	return (compat, options) => {
+		const { operationType, operationName, variables, fieldsBuilder } = compat.value;
+		const operationTypeName = schema.operations[operationType];
+		return Operation.create((() => buildOperationArtifact({
+			schema,
+			operationType,
+			operationTypeName,
+			operationName,
+			variables,
+			fieldsFactory: fieldsBuilder,
+			adapter: resolvedAdapter,
+			metadata: options?.metadata,
+			transformDocument: options?.transformDocument,
+			adapterTransformDocument: transformDocument
+		})));
+	};
+};
+
 //#endregion
 //#region packages/core/src/composer/fragment.ts
 /**
@@ -1109,18 +1356,6 @@ const createGqlFragmentComposers = (schema, _adapter) => {
 	return mapValues(schema.object, (_, typename) => createFragmentComposer(typename));
 };
 
-//#endregion
-//#region packages/core/src/types/metadata/adapter.ts
-/**
-* Creates the default adapter instance.
-* @internal
-*/
-const createDefaultAdapter = () => ({ aggregateFragmentMetadata: (fragments) => fragments.map((m) => m.metadata) });
-/**
-* The default adapter instance.
-*/
-const defaultMetadataAdapter = createDefaultAdapter();
-
 //#endregion
 //#region packages/core/src/composer/operation.ts
 /**
@@ -1149,86 +1384,18 @@ const createOperationComposerFactory = (schema, adapter, transformDocument) => {
 		const operationTypeName = schema.operations[operationType];
 		if (operationTypeName === null) throw new Error(`Operation type ${operationType} is not defined in schema roots`);
 		return (options) => {
-			return Operation.create(() => {
-				const { name: operationName } = options;
-				const variables = options.variables ?? {};
-				const $ = createVarRefs(variables);
-				const f = createFieldFactories(schema, operationTypeName);
-				const { result: fields, usages: fragmentUsages } = withFragmentUsageCollection(() => options.fields({
-					f,
-					$
-				}));
-				const document = buildDocument({
-					operationName,
-					operationType,
-					variables,
-					fields,
-					schema
-				});
-				const variableNames = Object.keys(variables);
-				if (!fragmentUsages.some((u) => u.metadataBuilder) && !options.metadata && !transformDocument && !options.transformDocument) return {
-					operationType,
-					operationName,
-					schemaLabel: schema.label,
-					variableNames,
-					documentSource: () => fields,
-					document,
-					metadata: void 0
-				};
-				const aggregateFragmentMetadata = (resolvedFragmentMetadata) => {
-					const fragmentMetaInfos = fragmentUsages.map((usage, index) => ({
-						metadata: resolvedFragmentMetadata[index],
-						fieldPath: usage.path
-					}));
-					return resolvedAdapter.aggregateFragmentMetadata(fragmentMetaInfos);
-				};
-				const fragmentMetadataResults = fragmentUsages.map((usage) => usage.metadataBuilder ? usage.metadataBuilder() : void 0);
-				const hasAsyncFragmentMetadata = fragmentMetadataResults.some((r) => isPromiseLike(r));
-				const buildOperationMetadata = (aggregatedFragmentMetadata) => {
-					const schemaLevel = resolvedAdapter.schemaLevel;
-					return options.metadata?.({
-						$,
-						document,
-						fragmentMetadata: aggregatedFragmentMetadata,
-						schemaLevel
-					});
-				};
-				const makeCreateDefinition = (aggregated$1) => {
-					return ({ metadata }) => {
-						let finalDocument = options.transformDocument ? options.transformDocument({
-							document,
-							metadata
-						}) : document;
-						if (transformDocument) finalDocument = transformDocument({
-							document: finalDocument,
-							operationName,
-							operationType,
-							variableNames,
-							schemaLevel: resolvedAdapter.schemaLevel,
-							fragmentMetadata: aggregated$1
-						});
-						return {
-							operationType,
-							operationName,
-							schemaLabel: schema.label,
-							variableNames,
-							documentSource: () => fields,
-							document: finalDocument,
-							metadata
-						};
-					};
-				};
-				if (hasAsyncFragmentMetadata) return Promise.all(fragmentMetadataResults).then(async (resolvedFragmentMetadata) => {
-					const aggregated$1 = aggregateFragmentMetadata(resolvedFragmentMetadata);
-					const operationMetadata = await buildOperationMetadata(aggregated$1);
-					return makeCreateDefinition(aggregated$1)({ metadata: operationMetadata });
-				});
-				const aggregated = aggregateFragmentMetadata(fragmentMetadataResults);
-				const createDefinition = makeCreateDefinition(aggregated);
-				const operationMetadataResult = buildOperationMetadata(aggregated);
-				if (isPromiseLike(operationMetadataResult)) return operationMetadataResult.then((metadata) => createDefinition({ metadata }));
-				return createDefinition({ metadata: operationMetadataResult });
-			});
+			return Operation.create((() => buildOperationArtifact({
+				schema,
+				operationType,
+				operationTypeName,
+				operationName: options.name,
+				variables: options.variables ?? {},
+				fieldsFactory: options.fields,
+				adapter: resolvedAdapter,
+				metadata: options.metadata,
+				transformDocument: options.transformDocument,
+				adapterTransformDocument: transformDocument
+			})));
 		};
 	};
 };
@@ -1488,9 +1655,20 @@ const createGqlElementComposer = (schema, options) => {
 	const createOperationComposer = createOperationComposerFactory(schema, metadataAdapter, transformDocument);
 	const transformedContext = require_context_transformer.applyContextTransformer({
 		fragment,
-		query: { operation: createOperationComposer("query") },
-		mutation: { operation: createOperationComposer("mutation") },
-		subscription: { operation: createOperationComposer("subscription") },
+		query: {
+			operation: createOperationComposer("query"),
+			compat: createCompatComposer(schema, "query")
+		},
+		mutation: {
+			operation: createOperationComposer("mutation"),
+			compat: createCompatComposer(schema, "mutation")
+		},
+		subscription: {
+			operation: createOperationComposer("subscription"),
+			compat: createCompatComposer(schema, "subscription")
+		},
+		define: (factory) => GqlDefine.create(factory),
+		extend: createExtendComposer(schema, metadataAdapter, transformDocument),
 		$var: createVarBuilder(inputTypeMethods),
 		$dir: directiveMethods ?? createStandardDirectives(),
 		$colocate: createColocateHelper(),
@@ -1760,6 +1938,7 @@ const generateInputTypeFromSpecifiers = (schema, specifiers, options = {}) => {
 
 //#endregion
 exports.Fragment = Fragment;
+exports.GqlDefine = GqlDefine;
 exports.GqlElement = GqlElement;
 exports.Operation = Operation;
 exports.VarRef = VarRef;
@@ -1768,14 +1947,17 @@ exports.applyTypeModifier = applyTypeModifier;
 exports.buildArgumentValue = buildArgumentValue;
 exports.buildConstValueNode = buildConstValueNode;
 exports.buildDocument = buildDocument;
+exports.buildOperationArtifact = buildOperationArtifact;
 exports.buildOperationTypeNode = buildOperationTypeNode;
 exports.buildWithTypeModifier = buildWithTypeModifier;
 exports.calculateFieldType = calculateFieldType;
 exports.calculateFieldsType = calculateFieldsType;
 exports.createColocateHelper = createColocateHelper;
+exports.createCompatComposer = createCompatComposer;
 exports.createDefaultAdapter = createDefaultAdapter;
 exports.createDirectiveBuilder = createDirectiveBuilder;
 exports.createDirectiveMethod = createDirectiveMethod;
+exports.createExtendComposer = createExtendComposer;
 exports.createFieldFactories = createFieldFactories;
 exports.createGqlElementComposer = createGqlElementComposer;
 exports.createGqlFragmentComposers = createGqlFragmentComposers;