@contember/bindx 0.1.0

package/src/schema/SchemaRegistry.ts

@@ -0,0 +1,286 @@
+import type { ContemberSchema } from './ContemberSchema.js'
+import type {
+	EntitySchemaDef,
+	FieldDef,
+	HasManyRelationDef,
+	HasOneRelationDef,
+	RelationType,
+	SchemaDefinition,
+} from './types.js'
+
+/**
+ * Runtime registry for entity schemas.
+ * Provides lookups for entity definitions, relation targets, and field types.
+ */
+export class SchemaRegistry<TModels extends Record<string, object> = Record<string, object>> {
+	private readonly entityDefs: Map<string, EntitySchemaDef>
+
+	constructor(definition: SchemaDefinition<TModels>) {
+		this.entityDefs = new Map()
+
+		for (const [entityName, entityDef] of Object.entries(definition.entities)) {
+			this.entityDefs.set(entityName, normalizeEntityDef(entityDef as EntitySchemaDef))
+		}
+	}
+
+	/**
+	 * Creates a SchemaRegistry from a ContemberSchema (loaded from API or injected).
+	 * This is the preferred way to create a SchemaRegistry at runtime.
+	 */
+	static fromContemberSchema(schema: ContemberSchema): SchemaRegistry {
+		const entities: Record<string, EntitySchemaDef> = {}
+
+		for (const entityName of schema.getEntityNames()) {
+			const entity = schema.getEntity(entityName)
+			if (!entity) continue
+
+			const fields: Record<string, FieldDef> = {}
+
+			for (const [fieldName, field] of entity.fields) {
+				if (field.__typename === '_Column') {
+					fields[fieldName] = { type: 'scalar' }
+				} else if (field.__typename === '_Relation') {
+					const isMany = field.type === 'OneHasMany' || field.type === 'ManyHasMany'
+					if (isMany) {
+						fields[fieldName] = {
+							type: 'hasMany',
+							target: field.targetEntity,
+							inverse: field.side === 'owning' ? field.inversedBy ?? undefined : field.ownedBy,
+						}
+					} else {
+						fields[fieldName] = {
+							type: 'hasOne',
+							target: field.targetEntity,
+							inverse: field.side === 'owning' ? field.inversedBy ?? undefined : field.ownedBy,
+						}
+					}
+				}
+			}
+
+			entities[entityName] = { fields }
+		}
+
+		return new SchemaRegistry({ entities } as SchemaDefinition<Record<string, object>>)
+	}
+
+	/**
+	 * Gets the entity names defined in the schema
+	 */
+	getEntityNames(): string[] {
+		return Array.from(this.entityDefs.keys())
+	}
+
+	/**
+	 * Checks if an entity type exists in the schema
+	 */
+	hasEntity(entityType: string): boolean {
+		return this.entityDefs.has(entityType)
+	}
+
+	/**
+	 * Gets the schema definition for an entity type
+	 */
+	getEntityDef(entityType: string): EntitySchemaDef | undefined {
+		return this.entityDefs.get(entityType)
+	}
+
+	/**
+	 * Gets the field definition for a specific field on an entity
+	 */
+	getFieldDef(entityType: string, fieldName: string): FieldDef | undefined {
+		const entityDef = this.entityDefs.get(entityType)
+		if (!entityDef) return undefined
+		return entityDef.fields[fieldName]
+	}
+
+	/**
+	 * Gets the enum values for an enum field.
+	 * Returns undefined if the field is not an enum or doesn't exist.
+	 */
+	getEnumValues(entityType: string, fieldName: string): readonly string[] | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef || fieldDef.type !== 'enum') return undefined
+		return fieldDef.values
+	}
+
+	/**
+	 * Gets the enum name for an enum field.
+	 * Returns undefined if the field is not an enum or doesn't exist.
+	 */
+	getEnumName(entityType: string, fieldName: string): string | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef || fieldDef.type !== 'enum') return undefined
+		return fieldDef.enumName
+	}
+
+	/**
+	 * Gets the column type for a scalar field (e.g. 'String', 'Integer', 'Date').
+	 * Returns undefined if the field is not a scalar or doesn't exist.
+	 */
+	getColumnType(entityType: string, fieldName: string): string | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef || fieldDef.type !== 'scalar') return undefined
+		return fieldDef.columnType
+	}
+
+	/**
+	 * Gets the target entity type for a relation field.
+	 * Returns undefined if the field is not a relation or doesn't exist.
+	 */
+	getRelationTarget(entityType: string, fieldName: string): string | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef) return undefined
+
+		if (fieldDef.type === 'hasOne' || fieldDef.type === 'hasMany') {
+			return fieldDef.target
+		}
+
+		return undefined
+	}
+
+	/**
+	 * Gets the relation type for a field (hasOne or hasMany).
+	 * Returns undefined if the field is not a relation.
+	 */
+	getRelationType(entityType: string, fieldName: string): RelationType | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef) return undefined
+
+		if (fieldDef.type === 'hasOne' || fieldDef.type === 'hasMany') {
+			return fieldDef.type
+		}
+
+		return undefined
+	}
+
+	/**
+	 * Checks if a field is a relation (hasOne or hasMany)
+	 */
+	isRelation(entityType: string, fieldName: string): boolean {
+		return this.getRelationType(entityType, fieldName) !== undefined
+	}
+
+	/**
+	 * Checks if a field is a has-one relation
+	 */
+	isHasOne(entityType: string, fieldName: string): boolean {
+		return this.getRelationType(entityType, fieldName) === 'hasOne'
+	}
+
+	/**
+	 * Checks if a field is a has-many relation
+	 */
+	isHasMany(entityType: string, fieldName: string): boolean {
+		return this.getRelationType(entityType, fieldName) === 'hasMany'
+	}
+
+	/**
+	 * Checks if a field is a scalar (non-relation) field
+	 */
+	isScalar(entityType: string, fieldName: string): boolean {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		return fieldDef?.type === 'scalar'
+	}
+
+	/**
+	 * Gets the inverse field name for a relation.
+	 * Returns undefined if no inverse is defined.
+	 */
+	getInverseField(entityType: string, fieldName: string): string | undefined {
+		const fieldDef = this.getFieldDef(entityType, fieldName)
+		if (!fieldDef) return undefined
+		if (fieldDef.type === 'scalar') return undefined
+
+		return (fieldDef as HasOneRelationDef | HasManyRelationDef).inverse
+	}
+
+	/**
+	 * Gets all scalar field names for an entity
+	 */
+	getScalarFields(entityType: string): string[] {
+		const entityDef = this.entityDefs.get(entityType)
+		if (!entityDef) return []
+
+		return Object.entries(entityDef.fields)
+			.filter(([_, def]) => def.type === 'scalar')
+			.map(([name]) => name)
+	}
+
+	/**
+	 * Gets all relation field names for an entity
+	 */
+	getRelationFields(entityType: string): string[] {
+		const entityDef = this.entityDefs.get(entityType)
+		if (!entityDef) return []
+
+		return Object.entries(entityDef.fields)
+			.filter(([_, def]) => def.type === 'hasOne' || def.type === 'hasMany')
+			.map(([name]) => name)
+	}
+
+	/**
+	 * Gets all field names for an entity
+	 */
+	getAllFields(entityType: string): string[] {
+		const entityDef = this.entityDefs.get(entityType)
+		if (!entityDef) return []
+
+		return Object.keys(entityDef.fields)
+	}
+
+	/**
+	 * Validates that all relation targets exist in the schema.
+	 * Throws an error if any target is missing.
+	 */
+	validate(): void {
+		for (const [entityName, entityDef] of this.entityDefs) {
+			for (const [fieldName, fieldDef] of Object.entries(entityDef.fields)) {
+				if (fieldDef.type === 'hasOne' || fieldDef.type === 'hasMany') {
+					if (!this.entityDefs.has(fieldDef.target)) {
+						throw new Error(
+							`Invalid schema: Entity "${entityName}" field "${fieldName}" references ` +
+								`unknown entity "${fieldDef.target}"`,
+						)
+					}
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Normalizes field definitions from Contember SchemaNames format
+ * (column/one/many with entity) to bindx FieldDef format (scalar/hasOne/hasMany with target).
+ */
+function normalizeEntityDef(entityDef: EntitySchemaDef): EntitySchemaDef {
+	const fields: Record<string, FieldDef> = {}
+	let needsNormalization = false
+
+	for (const [fieldName, fieldDef] of Object.entries(entityDef.fields)) {
+		const raw = fieldDef as unknown as Record<string, unknown>
+		const type = raw['type'] as string
+
+		if (type === 'column') {
+			fields[fieldName] = { type: 'scalar' }
+			needsNormalization = true
+		} else if (type === 'one') {
+			fields[fieldName] = {
+				type: 'hasOne',
+				target: (raw['entity'] as string) ?? (raw['target'] as string),
+				inverse: raw['inverse'] as string | undefined,
+			}
+			needsNormalization = true
+		} else if (type === 'many') {
+			fields[fieldName] = {
+				type: 'hasMany',
+				target: (raw['entity'] as string) ?? (raw['target'] as string),
+				inverse: raw['inverse'] as string | undefined,
+			}
+			needsNormalization = true
+		} else {
+			fields[fieldName] = fieldDef
+		}
+	}
+
+	return needsNormalization ? { fields } : entityDef
+}

package/src/schema/index.ts

@@ -0,0 +1,51 @@
+export {
+	type RelationType,
+	type ScalarFieldDef,
+	type HasOneRelationDef,
+	type HasManyRelationDef,
+	type FieldDef,
+	type EntitySchemaDef,
+	type SchemaDefinition,
+	type InferModel,
+	type InferEntityNames,
+	type EntityDef,
+	type InferEntityDef,
+	scalar,
+	enumScalar,
+	type EnumFieldDef,
+	hasOne,
+	hasMany,
+	defineSchema,
+	entityDef,
+	roleEntityDef,
+} from './types.js'
+
+export {
+	type UnionToIntersection,
+	type RoleNames,
+	type CommonEntity,
+	type EntityForRoles,
+	type ResolveEntity,
+	type SingleRoleMap,
+	type DefaultRole,
+	DEFAULT_ROLE,
+} from './roles.js'
+
+export { SchemaRegistry } from './SchemaRegistry.js'
+
+export {
+	type SchemaColumnType,
+	type SchemaColumn,
+	type SchemaRelationOrderBy,
+	type OwningRelation,
+	type InverseRelation,
+	type SchemaRelation,
+	type SchemaField,
+	type SchemaEntity,
+	type SchemaEnum,
+	type ContemberSchemaStore,
+	type RawContemberSchema,
+	ContemberSchema,
+} from './ContemberSchema.js'
+
+export { SchemaLoader, type SchemaLoaderClient } from './SchemaLoader.js'

package/src/schema/roles.ts

@@ -0,0 +1,83 @@
+/**
+ * Role-aware type utilities for bindx.
+ *
+ * The role system allows per-role field access control at the type level.
+ * Default (no role) = narrowest scope (fields ALL roles can access).
+ * Specifying roles = expanding scope (union of capabilities for those roles).
+ */
+
+// ============================================================================
+// Core Utility Types
+// ============================================================================
+
+/**
+ * Converts a union type to an intersection type.
+ * Used to merge field sets from multiple roles.
+ *
+ * @example
+ * UnionToIntersection<{ a: 1 } | { b: 2 }> = { a: 1 } & { b: 2 }
+ */
+export type UnionToIntersection<U> =
+	(U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never
+
+// ============================================================================
+// Role Map Types
+// ============================================================================
+
+/**
+ * Extracts all role names from a role map.
+ */
+export type RoleNames<TRoleMap extends Record<string, object>> = keyof TRoleMap & string
+
+/**
+ * Default entity type — the narrowest scope.
+ * Returns a union of all role entity types, so only common fields are accessible via keyof.
+ *
+ * @example
+ * CommonEntity<{ admin: { id: string; secret: string }; public: { id: string } }>
+ * // = { id: string; secret: string } | { id: string }
+ * // Only `id` is accessible (common to all roles)
+ */
+export type CommonEntity<TRoleMap extends Record<string, object>> = TRoleMap[keyof TRoleMap]
+
+/**
+ * Entity type for specific roles — expanded scope.
+ * Returns an intersection of the specified roles' entity types,
+ * giving access to all fields from any of those roles.
+ *
+ * @example
+ * EntityForRoles<{ admin: { id: string; secret: string }; editor: { id: string; notes: string } }, 'admin'>
+ * // = { id: string; secret: string }
+ *
+ * EntityForRoles<{ admin: { id: string; secret: string }; editor: { id: string; notes: string } }, 'admin' | 'editor'>
+ * // = { id: string; secret: string } & { id: string; notes: string }
+ * // = { id: string; secret: string; notes: string }
+ */
+export type EntityForRoles<
+	TRoleMap extends Record<string, object>,
+	TRoles extends keyof TRoleMap,
+> = UnionToIntersection<TRoleMap[TRoles]> & object
+
+/**
+ * Resolves the entity type based on whether roles are specified.
+ * - No roles (TRoles = never): returns CommonEntity (narrowest)
+ * - With roles: returns EntityForRoles (expanded)
+ */
+export type ResolveEntity<
+	TRoleMap extends Record<string, object>,
+	TRoles extends string,
+> = [TRoles] extends [never]
+	? CommonEntity<TRoleMap>
+	: EntityForRoles<TRoleMap, TRoles & keyof TRoleMap>
+
+/**
+ * Sentinel role name used when no ACL roles are defined.
+ * entityDef<Article>('Article') wraps as { _default: Article }.
+ */
+export const DEFAULT_ROLE = '_default' as const
+export type DefaultRole = typeof DEFAULT_ROLE
+
+/**
+ * Wraps a single entity type as a single-role map with the _default role.
+ */
+export type SingleRoleMap<TEntity extends object> = { readonly [K in DefaultRole]: TEntity }

package/src/schema/types.ts

@@ -0,0 +1,238 @@
+/**
+ * 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 }
+}