@contember/bindx 0.1.4 → 0.1.8

package/src/schema/types.ts

@@ -1,238 +1,21 @@
-/**
- * Schema type definitions for bindx.
- * Provides type-safe entity and relation definitions.
- */
-
-import type { CommonEntity, SingleRoleMap } from './roles.js'
-
-/**
- * Relation type discriminator
- */
-export type RelationType = 'hasOne' | 'hasMany'
-
-/**
- * Scalar field definition
- */
-export interface ScalarFieldDef {
-	readonly type: 'scalar'
-	readonly columnType?: string
-}
-
-/**
- * Enum scalar field definition — carries the allowed values at runtime
- */
-export interface EnumFieldDef {
-	readonly type: 'enum'
-	readonly enumName: string
-	readonly values: readonly string[]
-}
-
-/**
- * Has-one relation definition
- */
-export interface HasOneRelationDef<TTarget extends string = string> {
-	readonly type: 'hasOne'
-	readonly target: TTarget
-	/** Inverse field name on the target entity (for bidirectional relations) */
-	readonly inverse?: string
-}
-
-/**
- * Has-many relation definition
- */
-export interface HasManyRelationDef<TTarget extends string = string> {
-	readonly type: 'hasMany'
-	readonly target: TTarget
-	/** Inverse field name on the target entity (for bidirectional relations) */
-	readonly inverse?: string
-}
-
-/**
- * Union of all field definition types
- */
-export type FieldDef<TTarget extends string = string> =
-	| ScalarFieldDef
-	| EnumFieldDef
-	| HasOneRelationDef<TTarget>
-	| HasManyRelationDef<TTarget>
-
-/**
- * Entity schema definition - maps field names to their definitions
- */
-export interface EntitySchemaDef<TEntityNames extends string = string> {
-	readonly fields: Record<string, FieldDef<TEntityNames>>
-}
-
-/**
- * Complete schema definition mapping entity names to their schemas.
- * TModels provides the TypeScript types for each entity.
- */
-export interface SchemaDefinition<
-	TModels extends { [K in keyof TModels]: object },
-	TEntityNames extends string = keyof TModels & string,
-> {
-	readonly entities: {
-		[K in TEntityNames]: EntitySchemaDef<TEntityNames>
-	}
-}
-
-/**
- * Helper function to create a scalar field definition
- */
-export function scalar(): ScalarFieldDef {
-	return { type: 'scalar' }
-}
-
-/**
- * Helper function to create an enum scalar field definition with allowed values.
- */
-export function enumScalar<T extends string>(enumName: string, values: readonly T[]): EnumFieldDef {
-	return { type: 'enum', enumName, values }
-}
-
-/**
- * Helper function to create a has-one relation definition
- */
-export function hasOne<TTarget extends string>(
-	target: TTarget,
-	options?: { inverse?: string },
-): HasOneRelationDef<TTarget> {
-	return {
-		type: 'hasOne',
-		target,
-		inverse: options?.inverse,
-	}
-}
-
-/**
- * Helper function to create a has-many relation definition
- */
-export function hasMany<TTarget extends string>(
-	target: TTarget,
-	options?: { inverse?: string },
-): HasManyRelationDef<TTarget> {
-	return {
-		type: 'hasMany',
-		target,
-		inverse: options?.inverse,
-	}
-}
-
-/**
- * Helper function to define a complete schema with full type inference.
- *
- * @example
- * ```typescript
- * interface Author {
- *   id: string
- *   name: string
- *   articles: Article[]
- * }
- *
- * interface Article {
- *   id: string
- *   title: string
- *   author: Author
- * }
- *
- * const schema = defineSchema<{
- *   Author: Author
- *   Article: Article
- * }>({
- *   entities: {
- *     Author: {
- *       fields: {
- *         id: scalar(),
- *         name: scalar(),
- *         articles: hasMany('Article', { inverse: 'author' })
- *       }
- *     },
- *     Article: {
- *       fields: {
- *         id: scalar(),
- *         title: scalar(),
- *         author: hasOne('Author', { inverse: 'articles' })
- *       }
- *     }
- *   }
- * })
- * ```
- */
-export function defineSchema<TModels extends { [K in keyof TModels]: object }>(
-	definition: SchemaDefinition<TModels>,
-): SchemaDefinition<TModels> {
-	return definition
-}
-
-/**
- * Infers the model type for a given entity name from a schema
- */
-export type InferModel<
-	TSchema extends SchemaDefinition<any>,
-	TEntityName extends keyof TSchema['entities'],
-> = TSchema extends SchemaDefinition<infer TModels>
-	? TEntityName extends keyof TModels
-		? TModels[TEntityName]
-		: never
-	: never
-
-/**
- * Infers all entity names from a schema
- */
-export type InferEntityNames<TSchema extends SchemaDefinition<any>> = keyof TSchema['entities'] & string
-
-// ============================================================================
-// Entity Definitions (type-safe entity references)
-// ============================================================================
-
-/**
- * A type-safe reference to an entity in the schema.
- * Carries a role map as a phantom type parameter: Record<roleName, entityType>.
- *
- * For schemas without ACL, the role map is `{ _default: TEntity }`.
- * For schemas with ACL, each role maps to a per-role entity type.
- *
- * @example
- * ```ts
- * // Without roles (convenience):
- * const Article = entityDef<ArticleType>('Article')  // → EntityDef<{ _default: ArticleType }>
- *
- * // With roles (generator):
- * const Article = roleEntityDef<{ admin: Article$admin; public: Article$public }>('Article')
- * ```
- */
-export interface EntityDef<TRoleMap extends Record<string, object> = Record<string, object>> {
-	readonly $name: string
-	/** @internal phantom type for role map — not present at runtime */
-	readonly $roleMap?: TRoleMap
-	/** @internal reference to the schema definition for collection-time field lookups */
-	readonly $schema?: SchemaDefinition<Record<string, object>>
-}
-
-/**
- * Infers the common (default) entity type from an EntityDef.
- * Returns the union of all role entity types — only common fields are accessible.
- */
-export type InferEntityDef<T> = T extends EntityDef<infer TRoleMap> ? CommonEntity<TRoleMap> : never
-
-/**
- * Creates a type-safe entity definition reference.
- * Wraps the entity type in a single-role map: `{ _default: TEntity }`.
- *
- * @param name - The entity name as used in the schema
- * @param schema - Optional schema definition for collection-time field lookups
- */
-export function entityDef<TEntity extends object>(name: string, schema?: SchemaDefinition<Record<string, object>>): EntityDef<SingleRoleMap<TEntity>> {
-	return schema ? { $name: name, $schema: schema } : { $name: name }
-}
-
-/**
- * Creates a role-aware entity definition reference.
- * Used by the generator when ACL roles are present.
- *
- * @param name - The entity name as used in the schema
- * @param schema - Optional schema definition for collection-time field lookups
- */
-export function roleEntityDef<TRoleMap extends Record<string, object>>(name: string, schema?: SchemaDefinition<Record<string, object>>): EntityDef<TRoleMap> {
-	return schema ? { $name: name, $schema: schema } : { $name: name }
-}
+export {
+	type RelationType,
+	type ScalarFieldDef,
+	type HasOneRelationDef,
+	type HasManyRelationDef,
+	type FieldDef,
+	type EntitySchemaDef,
+	type SchemaDefinition,
+	type InferModel,
+	type InferEntityNames,
+	type EntityDef,
+	type InferEntityDef,
+	type EnumFieldDef,
+	scalar,
+	enumScalar,
+	hasOne,
+	hasMany,
+	defineSchema,
+	entityDef,
+	roleEntityDef,
+} from '@contember/bindx-client'

package/src/selection/SelectionMetaCollector.ts

@@ -1,122 +1 @@
-import type { SelectionMeta, SelectionFieldMeta } from './types.js'
-import { generateHasManyAlias } from '../utils/aliasGenerator.js'
-
-/**
- * Class for collecting field selection metadata during collection phase
- */
-export class SelectionMetaCollector implements SelectionMeta {
-	readonly fields = new Map<string, SelectionFieldMeta>()
-
-	/**
-	 * Add a field to the selection.
-	 *
-	 * For has-many fields with parameters (filter, orderBy, limit, offset),
-	 * uses alias as the key to allow multiple instances of the same field
-	 * with different parameters.
-	 */
-	addField(fieldMeta: SelectionFieldMeta): void {
-		let key: string
-
-		// For has-many fields with parameters, use alias as the key
-		// This allows multiple HasMany for the same field with different params
-		if (fieldMeta.isArray && fieldMeta.hasManyParams) {
-			const hasParams = fieldMeta.hasManyParams.filter !== undefined ||
-				fieldMeta.hasManyParams.orderBy !== undefined ||
-				fieldMeta.hasManyParams.limit !== undefined ||
-				fieldMeta.hasManyParams.offset !== undefined
-
-			if (hasParams) {
-				// Generate auto-alias if alias equals fieldName
-				if (fieldMeta.alias === fieldMeta.fieldName) {
-					fieldMeta.alias = generateHasManyAlias(fieldMeta.fieldName, fieldMeta.hasManyParams)
-				}
-				// Use alias-based key for has-many with params
-				const pathWithAlias = [...fieldMeta.path.slice(0, -1), fieldMeta.alias]
-				key = pathWithAlias.join('.')
-			} else {
-				key = fieldMeta.path.join('.')
-			}
-		} else {
-			key = fieldMeta.path.join('.')
-		}
-
-		const existing = this.fields.get(key)
-
-		if (existing) {
-			// Update relation/array flags if source has more specific info
-			if (fieldMeta.isRelation && !existing.isRelation) {
-				existing.isRelation = true
-			}
-			if (fieldMeta.isArray && !existing.isArray) {
-				existing.isArray = true
-			}
-			// Merge nested selections if both have them
-			if (fieldMeta.nested && existing.nested) {
-				mergeSelections(existing.nested, fieldMeta.nested)
-			} else if (fieldMeta.nested) {
-				existing.nested = fieldMeta.nested
-			}
-		} else {
-			this.fields.set(key, { ...fieldMeta })
-		}
-	}
-
-	/**
-	 * Get all root-level fields (not nested)
-	 */
-	getRootFields(): SelectionFieldMeta[] {
-		const result: SelectionFieldMeta[] = []
-		for (const field of this.fields.values()) {
-			if (field.path.length === 1) {
-				result.push(field)
-			}
-		}
-		return result
-	}
-
-	/**
-	 * Convert to plain object for serialization
-	 */
-	toJSON(): SelectionMeta {
-		return {
-			fields: new Map(this.fields),
-		}
-	}
-}
-
-/**
- * Merge two selections together
- */
-export function mergeSelections(target: SelectionMeta, source: SelectionMeta): void {
-	for (const [key, field] of source.fields) {
-		const existing = target.fields.get(key)
-		if (existing) {
-			// Update relation/array flags if source has more specific info
-			if (field.isRelation && !existing.isRelation) {
-				existing.isRelation = true
-			}
-			if (field.isArray && !existing.isArray) {
-				existing.isArray = true
-			}
-			// Merge hasManyParams if source has them
-			if (field.hasManyParams && !existing.hasManyParams) {
-				existing.hasManyParams = field.hasManyParams
-			}
-			// Merge nested selections
-			if (field.nested && existing.nested) {
-				mergeSelections(existing.nested, field.nested)
-			} else if (field.nested) {
-				existing.nested = field.nested
-			}
-		} else {
-			target.fields.set(key, { ...field })
-		}
-	}
-}
-
-/**
- * Create empty selection metadata
- */
-export function createEmptySelection(): SelectionMeta {
-	return { fields: new Map() }
-}
+export { SelectionMetaCollector, mergeSelections, createEmptySelection } from '@contember/bindx-client'

package/src/selection/SelectionScope.ts

@@ -1,208 +1 @@
-import type { SelectionMeta, SelectionFieldMeta } from './types.js'
-import { generateHasManyAlias } from '../utils/aliasGenerator.js'
-
-/**
- * HasMany parameters for filtering, ordering, pagination
- */
-export interface HasManyParams {
-	filter?: unknown
-	orderBy?: unknown
-	limit?: number
-	offset?: number
-	totalCount?: boolean
-}
-
-/**
- * Relation metadata stored at parent level
- */
-interface RelationMeta {
-	isArray: boolean
-	params?: HasManyParams
-}
-
-/**
- * Tree-based selection scope for collecting field selections.
- *
- * Unlike the flat path-based SelectionMetaCollector, SelectionScope
- * maintains a hierarchical tree structure that naturally represents
- * nested entity selections.
- *
- * Key benefits:
- * - Natural tree structure matches entity relationships
- * - No path string manipulation or collision risks
- * - Scope carries its context - no need for symbol passing
- * - Simple merge: just combine tree nodes
- */
-export class SelectionScope {
-	// Tree structure
-	private parent: SelectionScope | null = null
-	private children: Map<string, SelectionScope> = new Map()
-
-	// Fields at this level
-	private scalarFields: Set<string> = new Set()
-	private relationMeta: Map<string, RelationMeta> = new Map()
-
-	/**
-	 * Create or get a child scope for a relation field.
-	 * Automatically removes the field from scalars if it was there.
-	 * New child scopes always include 'id' as a minimum selection.
-	 */
-	child(fieldName: string): SelectionScope {
-		// Remove from scalars if it was added as scalar first
-		this.scalarFields.delete(fieldName)
-
-		let childScope = this.children.get(fieldName)
-		if (!childScope) {
-			childScope = new SelectionScope()
-			childScope.parent = this
-			childScope.addScalar('id')
-			this.children.set(fieldName, childScope)
-			this.relationMeta.set(fieldName, { isArray: false })
-		}
-		return childScope
-	}
-
-	/**
-	 * Add a scalar field to this scope.
-	 * If the field is already a relation, this is a no-op.
-	 */
-	addScalar(fieldName: string): void {
-		if (!this.children.has(fieldName)) {
-			this.scalarFields.add(fieldName)
-		}
-	}
-
-	/**
-	 * Mark a relation field as array (hasMany).
-	 */
-	markAsArray(fieldName: string): void {
-		const meta = this.relationMeta.get(fieldName)
-		if (meta) {
-			meta.isArray = true
-		}
-	}
-
-	/**
-	 * Set hasMany parameters for a relation field.
-	 */
-	setHasManyParams(fieldName: string, params: HasManyParams): void {
-		const meta = this.relationMeta.get(fieldName)
-		if (meta) {
-			meta.params = params
-		}
-	}
-
-	/**
-	 * Check if this scope has any fields (scalar or relation).
-	 */
-	hasFields(): boolean {
-		return this.scalarFields.size > 0 || this.children.size > 0
-	}
-
-	/**
-	 * Merge another scope into this one.
-	 * Scalar fields are added, relation children are recursively merged.
-	 */
-	merge(other: SelectionScope): void {
-		// Merge scalar fields
-		for (const field of other.scalarFields) {
-			this.addScalar(field)
-		}
-
-		// Merge relation children
-		for (const [fieldName, otherChild] of other.children) {
-			const thisChild = this.child(fieldName)
-			thisChild.merge(otherChild)
-
-			// Merge relation metadata
-			const otherMeta = other.relationMeta.get(fieldName)
-			if (otherMeta) {
-				const thisMeta = this.relationMeta.get(fieldName)!
-				if (otherMeta.isArray) {
-					thisMeta.isArray = true
-				}
-				if (otherMeta.params && !thisMeta.params) {
-					thisMeta.params = otherMeta.params
-				}
-			}
-		}
-	}
-
-	/**
-	 * Merge fields from a SelectionMeta into this scope.
-	 * Useful for integrating with existing fluent builder selections.
-	 */
-	mergeFromSelectionMeta(meta: SelectionMeta): void {
-		for (const [_key, field] of meta.fields) {
-			// Only process root-level fields
-			if (field.path.length !== 1) continue
-
-			if (field.isRelation && field.nested) {
-				const childScope = this.child(field.fieldName)
-				if (field.isArray) {
-					this.markAsArray(field.fieldName)
-				}
-				if (field.hasManyParams) {
-					this.setHasManyParams(field.fieldName, field.hasManyParams)
-				}
-				childScope.mergeFromSelectionMeta(field.nested)
-			} else {
-				this.addScalar(field.fieldName)
-			}
-		}
-	}
-
-	/**
-	 * Convert this scope to SelectionMeta format for backwards compatibility.
-	 * This allows the new SelectionScope to be used with existing query builders.
-	 *
-	 * For has-many fields with params, generates auto-alias to allow multiple
-	 * HasMany components for the same field with different parameters.
-	 */
-	toSelectionMeta(): SelectionMeta {
-		const fields = new Map<string, SelectionFieldMeta>()
-
-		// Add scalar fields
-		for (const fieldName of this.scalarFields) {
-			fields.set(fieldName, {
-				fieldName,
-				alias: fieldName,
-				path: [fieldName],
-				isRelation: false,
-				isArray: false,
-			})
-		}
-
-		// Add relation fields with nested selections
-		for (const [fieldName, childScope] of this.children) {
-			const meta = this.relationMeta.get(fieldName)!
-
-			// Generate alias for has-many fields with params
-			const alias = meta.isArray && meta.params
-				? generateHasManyAlias(fieldName, meta.params)
-				: fieldName
-
-			fields.set(alias, {
-				fieldName,
-				alias,
-				path: [fieldName],
-				isRelation: true,
-				isArray: meta.isArray,
-				nested: childScope.toSelectionMeta(),
-				hasManyParams: meta.params,
-			})
-		}
-
-		return { fields }
-	}
-
-	/**
-	 * Create a SelectionScope from an existing SelectionMeta.
-	 * Useful for converting explicit selections to scope format.
-	 */
-	static fromSelectionMeta(meta: SelectionMeta): SelectionScope {
-		const scope = new SelectionScope()
-		scope.mergeFromSelectionMeta(meta)
-		return scope
-	}
-}
+export { SelectionScope, type HasManyParams } from '@contember/bindx-client'