@contember/bindx 0.1.4 → 0.1.8

package/src/selection/buildQuery.ts

@@ -1,134 +1 @@
-import type { SelectionMeta, SelectionFieldMeta } from './types.js'
-
-/**
- * Query specification for a single field
- */
-export interface QueryFieldSpec {
-	/** Name of the field as it appears in the output */
-	name: string
-	/** Path to the field in the source entity */
-	sourcePath: string[]
-	/** For nested objects/entities */
-	nested?: QuerySpec
-	/** Whether this is an array/collection */
-	isArray?: boolean
-	/** For has-many: filter parameters */
-	filter?: unknown
-	/** For has-many: ordering parameters */
-	orderBy?: unknown
-	/** For has-many: limit */
-	limit?: number
-	/** For has-many: offset */
-	offset?: number
-	/** For has-many: request totalCount via paginateRelation */
-	totalCount?: boolean
-}
-
-/**
- * Query specification for fetching data.
- * Backend adapters use this to construct their queries.
- */
-export interface QuerySpec {
-	/** List of fields to fetch */
-	fields: QueryFieldSpec[]
-}
-
-/**
- * Builds a QuerySpec from SelectionMeta.
- * This is what gets passed to the backend adapter.
- *
- * @param meta - The selection metadata
- */
-export function buildQueryFromSelection(meta: SelectionMeta): QuerySpec {
-	const fields: QueryFieldSpec[] = []
-
-	// Always include 'id' field if not already selected
-	// This is needed for entity identity and HasOneAccessor to detect if relation exists
-	if (!meta.fields.has('id')) {
-		fields.push({
-			name: 'id',
-			sourcePath: ['id'],
-		})
-	}
-
-	for (const [_alias, fieldMeta] of meta.fields) {
-		// Skip relation fields where no nested fields were selected.
-		// This occurs when a relation handle is passed as a prop (e.g., HasManyDataGrid's `field` prop)
-		// without any of its fields being read during JSX collection. The consuming component
-		// is expected to handle its own data fetching for that relation.
-		if (fieldMeta.isRelation && fieldMeta.nested && fieldMeta.nested.fields.size === 0) {
-			continue
-		}
-		fields.push(buildFieldSpecFromSelection(fieldMeta))
-	}
-
-	return { fields }
-}
-
-/**
- * Builds a QueryFieldSpec from SelectionFieldMeta
- */
-function buildFieldSpecFromSelection(meta: SelectionFieldMeta): QueryFieldSpec {
-	const spec: QueryFieldSpec = {
-		name: meta.alias,
-		sourcePath: [meta.fieldName],
-	}
-
-	if (meta.isArray) {
-		spec.isArray = true
-
-		// Add has-many parameters
-		if (meta.hasManyParams) {
-			if (meta.hasManyParams.filter !== undefined) {
-				spec.filter = meta.hasManyParams.filter
-			}
-			if (meta.hasManyParams.orderBy !== undefined) {
-				spec.orderBy = meta.hasManyParams.orderBy
-			}
-			if (meta.hasManyParams.limit !== undefined) {
-				spec.limit = meta.hasManyParams.limit
-			}
-			if (meta.hasManyParams.offset !== undefined) {
-				spec.offset = meta.hasManyParams.offset
-			}
-			if (meta.hasManyParams.totalCount) {
-				spec.totalCount = true
-			}
-		}
-
-		if (meta.nested) {
-			spec.nested = buildQueryFromSelection(meta.nested)
-		}
-	} else if (meta.nested) {
-		spec.nested = buildQueryFromSelection(meta.nested)
-	}
-
-	return spec
-}
-
-/**
- * Collects all unique paths that need to be fetched.
- * Useful for debugging and optimization.
- */
-export function collectPaths(meta: SelectionMeta, basePath: string[] = []): string[][] {
-	const paths: string[][] = []
-
-	for (const [_alias, fieldMeta] of meta.fields) {
-		const fullPath = [...basePath, fieldMeta.fieldName]
-
-		if (fieldMeta.isArray && fieldMeta.nested) {
-			// For arrays, collect paths from nested metadata
-			const nestedPaths = collectPaths(fieldMeta.nested, fullPath)
-			paths.push(...nestedPaths)
-		} else if (fieldMeta.nested) {
-			// For nested objects, collect paths recursively
-			const nestedPaths = collectPaths(fieldMeta.nested, fullPath)
-			paths.push(...nestedPaths)
-		} else {
-			// Scalar field
-			paths.push(fullPath)
-		}
-	}
-
-	return paths
-}
+export { buildQueryFromSelection, collectPaths, type QuerySpec, type QueryFieldSpec } from '@contember/bindx-client'

package/src/selection/createFragment.ts

@@ -1,50 +1 @@
-import { createSelectionBuilder } from './createSelectionBuilder.js'
-import { SELECTION_META, type FluentFragment, type SelectionBuilder } from './types.js'
-
-/**
- * Creates a reusable fragment using the fluent builder API.
- *
- * This is a curried function - first call provides the model type,
- * second call provides the definer function.
- *
- * @example
- * ```ts
- * // Define a fragment
- * const AuthorFragment = createFragment<Author>()(e =>
- *   e.id().name().email()
- * )
- *
- * // Use in useEntity
- * const article = useEntity('Article', { id }, e =>
- *   e.title().author(AuthorFragment)
- * )
- *
- * // Or compose fragments
- * const ArticleFragment = createFragment<Article>()(e =>
- *   e.id().title()
- *    .author(AuthorFragment)
- *    .tags(TagFragment)
- * )
- * ```
- */
-export function createFragment<TModel>() {
-	return function <TResult extends object>(
-		definer: (builder: SelectionBuilder<TModel>) => SelectionBuilder<TModel, TResult, object>,
-	): FluentFragment<TModel, TResult> {
-		// Create initial builder
-		const builder = createSelectionBuilder<TModel>()
-
-		// Execute definer to get final builder with accumulated selections
-		const resultBuilder = definer(builder)
-
-		// Extract metadata
-		const meta = resultBuilder[SELECTION_META]
-
-		return {
-			__meta: meta,
-			__resultType: undefined as unknown as TResult,
-			__modelType: undefined as unknown as TModel,
-			__isFragment: true,
-		}
-	}
-}
+export { createFragment } from '@contember/bindx-client'

package/src/selection/createSelectionBuilder.ts

@@ -1,283 +1 @@
-import {
-	SELECTION_META,
-	type FluentFragment,
-	type SelectionBuilder,
-	type SelectionFieldMeta,
-	type SelectionMeta,
-	type HasManyOptions,
-} from './types.js'
-import { mergeSelections, SelectionMetaCollector } from './SelectionMetaCollector.js'
-import { generateHasManyAlias } from '../utils/aliasGenerator.js'
-
-/**
- * Creates a fluent selection builder for an entity type.
- * Uses Proxy to intercept method calls and build selection metadata.
- *
- * @example
- * ```ts
- * const builder = createSelectionBuilder<Article>()
- * const result = builder.id().title().author(a => a.name())
- * const meta = result[SELECTION_META]
- * ```
- */
-export function createSelectionBuilder<TEntity, TSelected extends object = object, THasManyParams extends object = object>(
-	initialMeta: SelectionMeta = { fields: new Map() },
-): SelectionBuilder<TEntity, TSelected, THasManyParams> {
-	const handler: ProxyHandler<object> = {
-		get(_target, prop: string | symbol) {
-			// Return metadata for introspection
-			if (prop === SELECTION_META) {
-				return initialMeta
-			}
-
-			// Type brand accessor
-			if (prop === '__selected') {
-				return undefined
-			}
-
-			// Skip internal symbols
-			if (typeof prop === 'symbol') {
-				return undefined
-			}
-
-			// Return a function that handles the field selection
-			return createFieldMethod<TEntity, TSelected, THasManyParams>(prop, initialMeta)
-		},
-		has(_target, prop: string | symbol) {
-			if (prop === SELECTION_META) {
-				return true
-			}
-			return false
-		},
-	}
-
-	return new Proxy({}, handler) as SelectionBuilder<TEntity, TSelected, THasManyParams>
-}
-
-/**
- * Creates a method for selecting a specific field.
- * The method signature depends on the field type (scalar, has-one, has-many).
- */
-function createFieldMethod<TEntity, TSelected extends object, THasManyParams extends object>(
-	fieldName: string,
-	currentMeta: SelectionMeta,
-) {
-	return function selectField(...args: unknown[]): SelectionBuilder<TEntity, object, object> {
-		// Parse arguments to determine what kind of selection this is
-		const { options, selector, fragment, fragments } = parseFieldArgs(args)
-
-		// Build field metadata
-		const fieldMeta: SelectionFieldMeta = {
-			fieldName,
-			alias: fieldName, // Will be updated below
-			path: [fieldName],
-			isRelation: false,
-			isArray: false,
-			nested: undefined,
-			hasManyParams: undefined,
-		}
-
-		// Handle relation with callback
-		if (typeof selector === 'function') {
-			const nestedBuilder = createSelectionBuilder<unknown>()
-			const resultBuilder = selector(nestedBuilder) as SelectionBuilder<unknown, object, object>
-			fieldMeta.nested = resultBuilder[SELECTION_META]
-			fieldMeta.isRelation = true
-
-			// Check if this looks like a has-many (options has filter/orderBy/limit)
-			if (options && isHasManyOptions(options)) {
-				fieldMeta.isArray = true
-				fieldMeta.hasManyParams = {
-					filter: (options as HasManyOptions).filter,
-					orderBy: (options as HasManyOptions).orderBy,
-					limit: (options as HasManyOptions).limit,
-					offset: (options as HasManyOptions).offset,
-					totalCount: (options as HasManyOptions).totalCount,
-				}
-			}
-		}
-
-		// Handle relation with single fragment
-		if (fragment && isFluentFragment(fragment)) {
-			fieldMeta.nested = fragment.__meta
-			fieldMeta.isRelation = true
-
-			// Check has-many params
-			if (options && isHasManyOptions(options)) {
-				fieldMeta.isArray = true
-				fieldMeta.hasManyParams = {
-					filter: (options as HasManyOptions).filter,
-					orderBy: (options as HasManyOptions).orderBy,
-					limit: (options as HasManyOptions).limit,
-					offset: (options as HasManyOptions).offset,
-					totalCount: (options as HasManyOptions).totalCount,
-				}
-			}
-		}
-
-		// Handle relation with multiple fragments (merged)
-		if (fragments && fragments.length > 0) {
-			// Merge all fragment selections into one
-			const mergedSelection = new SelectionMetaCollector()
-			for (const frag of fragments) {
-				mergeSelections(mergedSelection, frag.__meta)
-			}
-			fieldMeta.nested = mergedSelection
-			fieldMeta.isRelation = true
-
-			// Check has-many params
-			if (options && isHasManyOptions(options)) {
-				fieldMeta.isArray = true
-				fieldMeta.hasManyParams = {
-					filter: (options as HasManyOptions).filter,
-					orderBy: (options as HasManyOptions).orderBy,
-					limit: (options as HasManyOptions).limit,
-					offset: (options as HasManyOptions).offset,
-					totalCount: (options as HasManyOptions).totalCount,
-				}
-			}
-		}
-
-		// Determine alias:
-		// 1. Explicit alias from options takes priority
-		// 2. For has-many with params, auto-generate alias
-		// 3. Otherwise, use fieldName
-		const explicitAlias = (options as { as?: string } | undefined)?.as
-		if (explicitAlias) {
-			fieldMeta.alias = explicitAlias
-		} else if (fieldMeta.isArray && fieldMeta.hasManyParams) {
-			// Auto-generate alias for has-many with params
-			fieldMeta.alias = generateHasManyAlias(fieldName, fieldMeta.hasManyParams)
-		}
-		// else alias is already set to fieldName
-
-		// If it's a relation call without options but first arg is callback/fragment
-		// and there's no filter/orderBy, check if it's has-many by detecting array at runtime
-		// This is handled by the type system - if the field type is Array<T>, it will use HasManyMethod
-
-		// Create new metadata with this field added
-		const newMeta: SelectionMeta = {
-			fields: new Map(currentMeta.fields),
-		}
-		newMeta.fields.set(fieldMeta.alias, fieldMeta)
-
-		// Return new builder with accumulated selection
-		return createSelectionBuilder<TEntity, TSelected, THasManyParams>(newMeta)
-	}
-}
-
-/**
- * Type guard for HasManyOptions
- */
-function isHasManyOptions(value: unknown): value is HasManyOptions {
-	if (typeof value !== 'object' || value === null) {
-		return false
-	}
-	return 'filter' in value || 'orderBy' in value || 'limit' in value || 'offset' in value
-}
-
-/**
- * Type guard for FluentFragment
- */
-function isFluentFragment(value: unknown): value is FluentFragment<unknown, unknown> {
-	return (
-		value !== null &&
-		typeof value === 'object' &&
-		'__isFragment' in value &&
-		(value as FluentFragment<unknown, unknown>).__isFragment === true
-	)
-}
-
-/**
- * Parses the variable arguments to a field method.
- *
- * Possible call patterns:
- * - e.title()                           -> scalar, no args
- * - e.title({ as: 'x' })                -> scalar with alias
- * - e.author(a => a.name())             -> has-one with callback
- * - e.author(AuthorFragment)            -> has-one with fragment
- * - e.author(Frag1, Frag2, ...)         -> has-one with multiple fragments (merged)
- * - e.author({ as: 'x' }, a => a.name())-> has-one with alias + callback
- * - e.author({ as: 'x' }, AuthorFrag)   -> has-one with alias + fragment
- * - e.author({ as: 'x' }, Frag1, Frag2) -> has-one with alias + multiple fragments
- * - e.tags(t => t.name())               -> has-many with callback
- * - e.tags(TagFragment)                 -> has-many with fragment
- * - e.tags(Frag1, Frag2, ...)           -> has-many with multiple fragments (merged)
- * - e.tags({ filter: {} }, t => t.name()) -> has-many with options + callback
- * - e.tags({ filter: {} }, TagFragment)   -> has-many with options + fragment
- * - e.tags({ filter: {} }, Frag1, Frag2)  -> has-many with options + multiple fragments
- */
-function parseFieldArgs(args: unknown[]): {
-	options?: Record<string, unknown>
-	selector?: (builder: SelectionBuilder<unknown>) => SelectionBuilder<unknown, object, object>
-	fragment?: FluentFragment<unknown, unknown>
-	fragments?: FluentFragment<unknown, unknown>[]
-} {
-	if (args.length === 0) {
-		// Just field name, no args: e.title()
-		return {}
-	}
-
-	if (args.length === 1) {
-		const arg = args[0]
-		if (typeof arg === 'function') {
-			// Selector callback: e.author(a => a.name())
-			return { selector: arg as (builder: SelectionBuilder<unknown>) => SelectionBuilder<unknown, object, object> }
-		}
-		if (typeof arg === 'object' && arg !== null) {
-			if (isFluentFragment(arg)) {
-				// Fragment: e.author(AuthorFragment)
-				return { fragment: arg }
-			}
-			// Options without selector: e.title({ as: 'caption' })
-			return { options: arg as Record<string, unknown> }
-		}
-	}
-
-	// Check for multiple fragments: e.author(Frag1, Frag2, ...)
-	if (args.length >= 2 && args.every(isFluentFragment)) {
-		return { fragments: args as FluentFragment<unknown, unknown>[] }
-	}
-
-	if (args.length >= 2) {
-		const [first, ...rest] = args
-
-		// Check if first is options object
-		if (typeof first === 'object' && first !== null && !isFluentFragment(first)) {
-			const second = rest[0]
-
-			if (typeof second === 'function') {
-				// Options + selector: e.tags({ filter: {...} }, t => t.name())
-				return {
-					options: first as Record<string, unknown>,
-					selector: second as (builder: SelectionBuilder<unknown>) => SelectionBuilder<unknown, object, object>,
-				}
-			}
-
-			// Check for options + multiple fragments
-			if (rest.every(isFluentFragment)) {
-				if (rest.length === 1) {
-					// Options + single fragment: e.tags({ filter: {...} }, TagFragment)
-					return {
-						options: first as Record<string, unknown>,
-						fragment: rest[0] as FluentFragment<unknown, unknown>,
-					}
-				}
-				// Options + multiple fragments: e.tags({ filter: {} }, Frag1, Frag2)
-				return {
-					options: first as Record<string, unknown>,
-					fragments: rest as FluentFragment<unknown, unknown>[],
-				}
-			}
-		}
-	}
-
-	return {}
-}
-
-/**
- * Extracts SelectionMeta from a builder
- */
-export function getSelectionMeta(builder: SelectionBuilder<unknown, object, object>): SelectionMeta {
-	return builder[SELECTION_META]
-}
+export { createSelectionBuilder, getSelectionMeta } from '@contember/bindx-client'

package/src/selection/queryTypes.ts

@@ -1,135 +1,8 @@
-/**
- * Typed query parameter types for filter, orderBy, etc.
- *
- * Uses Input.Condition and Input.OrderDirection from @contember/schema
- * for scalar conditions, wrapped in entity-aware types that work with
- * plain TypeScript interfaces.
- */
-
-import { Input } from '@contember/schema'
-
-// ============================================================================
-// Re-export Contember types
-// ============================================================================
-
-/**
- * Condition operators for scalar values - re-exported from @contember/schema
- */
-export type ScalarCondition<T> = Input.Condition<T>
-
-/**
- * Order direction enum values - string literal union from Contember enum
- */
-export type OrderDirection = `${Input.OrderDirection}`
-
-// ============================================================================
-// Where Types (for filtering)
-// ============================================================================
-
-/**
- * Base composed where with AND/OR/NOT logic
- */
-export interface ComposedWhere<TEntity> {
-	readonly and?: readonly EntityWhere<TEntity>[]
-	readonly or?: readonly EntityWhere<TEntity>[]
-	readonly not?: EntityWhere<TEntity>
-}
-
-/**
- * Checks if a type is a "plain object" (entity) vs a scalar like Date
- * Date and other built-in objects are not treated as relations
- */
-type IsPlainObject<T> =
-	T extends Date ? false :
-	T extends Array<any> ? false :
-	T extends Function ? false :
-	T extends object ? true :
-	false
-
-/**
- * Field-level where clause for an entity
- * Maps each field to its appropriate condition type using Input.Condition
- */
-export type FieldsWhere<TEntity> = {
-	readonly [K in keyof TEntity]?:
-		NonNullable<TEntity[K]> extends Array<infer U>
-			? IsPlainObject<U> extends true
-				? EntityWhere<U> | null  // has-many: filter on related items (array of entities)
-				: Input.Condition<NonNullable<TEntity[K]>> | null  // scalar array: use Input.Condition on the array (supports hasSome, contains, etc.)
-			: IsPlainObject<NonNullable<TEntity[K]>> extends true
-				? EntityWhere<NonNullable<TEntity[K]>> | null  // has-one: filter on related entity
-				: Input.Condition<NonNullable<TEntity[K]>> | null  // scalar: use Input.Condition
-}
-
-/**
- * Full where type for an entity - combines composed and field conditions
- */
-export type EntityWhere<TEntity> = ComposedWhere<TEntity> & FieldsWhere<TEntity>
-
-// ============================================================================
-// OrderBy Types (for sorting)
-// ============================================================================
-
-/**
- * Order by clause for an entity
- * Each scalar field can have a direction, relations can have nested ordering
- */
-export type EntityOrderBy<TEntity> = {
-	readonly [K in keyof TEntity]?:
-		NonNullable<TEntity[K]> extends Array<any>
-			? never  // has-many cannot be ordered by directly
-			: IsPlainObject<NonNullable<TEntity[K]>> extends true
-				? EntityOrderBy<NonNullable<TEntity[K]>> | null  // has-one: nested ordering
-				: OrderDirection | null  // scalar: direction (including Date)
-} & {
-	readonly _random?: boolean
-	readonly _randomSeeded?: number
-}
-
-// ============================================================================
-// HasMany Options with Typed Parameters
-// ============================================================================
-
-/**
- * Options for has-many relation selection with typed filter/orderBy
- *
- * @typeParam TItem - The related entity type (array item type)
- * @typeParam TAlias - Optional alias for the field
- */
-export interface TypedHasManyOptions<
-	TItem,
-	TAlias extends string = string,
-> {
-	readonly as?: TAlias
-	readonly filter?: EntityWhere<TItem>
-	readonly orderBy?: readonly EntityOrderBy<TItem>[]
-	readonly limit?: number
-	readonly offset?: number
-	readonly totalCount?: boolean
-}
-
-/**
- * Alias-only options (for scalar or has-one with alias)
- */
-export interface AliasOptions<TAlias extends string = string> {
-	readonly as?: TAlias
-}
-
-// ============================================================================
-// Type Utilities
-// ============================================================================
-
-/**
- * Extracts the item type from an array type
- */
-export type ArrayItemType<T> = T extends Array<infer U> ? U : never
-
-/**
- * Checks if a type is an array
- */
-export type IsArray<T> = T extends Array<any> ? true : false
-
-/**
- * Extracts non-nullable type
- */
-export type NonNullableType<T> = Exclude<T, null | undefined>
+export {
+	type EntityWhere,
+	type EntityOrderBy,
+	type ScalarCondition,
+	type OrderDirection,
+	type TypedHasManyOptions,
+	type AliasOptions,
+} from '@contember/bindx-client'