@contember/bindx-generator 0.1.0

package/src/BindxGenerator.ts

@@ -0,0 +1,154 @@
+/**
+ * Main bindx schema generator
+ *
+ * Generates TypeScript schema files from Contember Model.Schema.
+ */
+
+import { Model, Acl } from '@contember/schema'
+import { EntityTypeSchemaGenerator } from './EntityTypeSchemaGenerator'
+import { EnumTypeSchemaGenerator } from './EnumTypeSchemaGenerator'
+import { NameSchemaGenerator } from './NameSchemaGenerator'
+import { RoleSchemaGenerator, type RoleSchemaGeneratorOptions } from './RoleSchemaGenerator'
+
+export interface BindxGeneratorOptions extends RoleSchemaGeneratorOptions {
+	// Reserved for future options
+}
+
+export interface GeneratedFiles {
+	'entities.ts': string
+	'names.ts'?: string
+	'enums.ts': string
+	'types.ts': string
+	'schema.ts': string
+	'index.ts': string
+}
+
+export class BindxGenerator {
+	private readonly entityTypeSchemaGenerator: EntityTypeSchemaGenerator
+	private readonly enumTypeSchemaGenerator: EnumTypeSchemaGenerator
+	private readonly nameSchemaGenerator: NameSchemaGenerator
+	private readonly roleSchemaGenerator: RoleSchemaGenerator
+
+	constructor(private readonly options: BindxGeneratorOptions = {}) {
+		this.entityTypeSchemaGenerator = new EntityTypeSchemaGenerator()
+		this.enumTypeSchemaGenerator = new EnumTypeSchemaGenerator()
+		this.nameSchemaGenerator = new NameSchemaGenerator()
+		this.roleSchemaGenerator = new RoleSchemaGenerator(options)
+	}
+
+	/**
+	 * Generate schema files
+	 */
+	generate(model: Model.Schema, acl?: Acl.Schema): GeneratedFiles {
+		const enumsCode = this.enumTypeSchemaGenerator.generate(model)
+		let entitiesCode = this.entityTypeSchemaGenerator.generate(model)
+		const namesSchema = this.nameSchemaGenerator.generate(model)
+
+		// Append per-role entity types if ACL is provided
+		if (acl) {
+			entitiesCode += '\n' + this.roleSchemaGenerator.generateRoleEntities(model, acl)
+		}
+
+		const namesCode = `import type { BindxSchemaNames } from './types'
+
+export const schemaNames: BindxSchemaNames = ${JSON.stringify(namesSchema, null, '\t')}
+`
+
+		const typesCode = this.generateTypesFile()
+		const schemaCode = acl
+			? this.roleSchemaGenerator.generateSchemaFile(model, acl)
+			: this.generateSchemaFile(model)
+
+		const indexCode = `export * from './enums'
+export * from './entities'
+export * from './names'
+export * from './types'
+export * from './schema'
+`
+
+		return {
+			'entities.ts': entitiesCode,
+			'names.ts': namesCode,
+			'enums.ts': enumsCode,
+			'types.ts': typesCode,
+			'schema.ts': schemaCode,
+			'index.ts': indexCode,
+		}
+	}
+
+	private generateSchemaFile(model: Model.Schema): string {
+		const entityNames = Object.values(model.entities).map(e => e.name).sort()
+
+		const imports = entityNames.join(', ')
+		const entries = entityNames
+			.map(name => `\t${name}: entityDef<${name}>('${name}', schemaDef),`)
+			.join('\n')
+
+		return `import { entityDef } from '@contember/bindx'
+import { schemaNamesToDef } from '@contember/bindx-react'
+import type { ${imports} } from './entities'
+import { schemaNames } from './names'
+
+const schemaDef = schemaNamesToDef(schemaNames)
+
+export const schema = {
+${entries}
+} as const
+`
+	}
+
+	private generateTypesFile(): string {
+		return `/**
+ * Shared types for bindx schema
+ */
+
+export interface BindxSchemaEntityNames {
+	readonly name: string
+	readonly scalars: readonly string[]
+	readonly fields: {
+		readonly [fieldName: string]:
+			| { readonly type: 'column'; readonly enumName?: string }
+			| { readonly type: 'one'; readonly entity: string }
+			| { readonly type: 'many'; readonly entity: string }
+	}
+}
+
+export interface BindxSchemaNames {
+	readonly entities: {
+		readonly [entityName: string]: BindxSchemaEntityNames
+	}
+	readonly enums: {
+		readonly [enumName: string]: readonly string[]
+	}
+}
+`
+	}
+}
+
+/**
+ * Generate bindx schema files from Contember model
+ *
+ * @example
+ * ```ts
+ * const files = generate(model)
+ * ```
+ */
+export function generate(
+	model: Model.Schema,
+	aclOrOptions?: Acl.Schema | BindxGeneratorOptions,
+	options?: BindxGeneratorOptions,
+): GeneratedFiles {
+	// Support both generate(model, acl, options) and generate(model, options)
+	let acl: Acl.Schema | undefined
+	let opts: BindxGeneratorOptions | undefined
+
+	if (aclOrOptions && 'roles' in aclOrOptions) {
+		acl = aclOrOptions
+		opts = options
+	} else {
+		opts = aclOrOptions as BindxGeneratorOptions | undefined
+	}
+
+	const generator = new BindxGenerator(opts)
+	return generator.generate(model, acl)
+}

package/src/EntityTypeSchemaGenerator.ts

@@ -0,0 +1,77 @@
+/**
+ * Entity type schema generator for bindx
+ * Generates TypeScript entity types from Contember model
+ * 
+ * Output format is designed to work with bindx's type system,
+ * separating columns, hasOne, and hasMany for proper type inference.
+ */
+
+import { Model } from '@contember/schema'
+import { acceptEveryFieldVisitor } from '@contember/schema-utils'
+import { columnToTsType, getEnumTypeName } from './utils'
+
+export class EntityTypeSchemaGenerator {
+	generate(model: Model.Schema): string {
+		let code = ''
+
+		// Import enum types
+		for (const enumName of Object.keys(model.enums)) {
+			code += `import type { ${getEnumTypeName(enumName)} } from './enums'\n`
+		}
+
+		// Add JSON type definitions
+		code += `
+export type JSONPrimitive = string | number | boolean | null
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray
+export type JSONObject = { readonly [K in string]?: JSONValue }
+export type JSONArray = readonly JSONValue[]
+
+`
+
+		// Generate entity types
+		for (const entity of Object.values(model.entities)) {
+			code += this.generateEntityTypeCode(model, entity)
+		}
+
+		// Generate schema type
+		code += '\n'
+		code += `export interface BindxEntities {\n`
+		for (const entity of Object.values(model.entities)) {
+			code += `\t${entity.name}: ${entity.name}\n`
+		}
+		code += '}\n\n'
+
+		code += `export interface BindxSchema {\n`
+		code += '\tentities: BindxEntities\n'
+		code += '}\n'
+
+		return code
+	}
+
+	private generateEntityTypeCode(model: Model.Schema, entity: Model.Entity): string {
+		let code = `export interface ${entity.name} {\n`
+
+		let columnsCode = ''
+		let hasOneCode = ''
+		let hasManyCode = ''
+
+		acceptEveryFieldVisitor(model, entity, {
+			visitHasMany: ctx => {
+				hasManyCode += `\t\t${ctx.relation.name}: ${ctx.targetEntity.name}[]\n`
+			},
+			visitHasOne: ctx => {
+				hasOneCode += `\t\t${ctx.relation.name}: ${ctx.targetEntity.name}\n`
+			},
+			visitColumn: ctx => {
+				columnsCode += `\t\t${ctx.column.name}: ${columnToTsType(ctx.column)}${ctx.column.nullable ? ' | null' : ''}\n`
+			},
+		})
+
+		code += columnsCode
+		code += hasOneCode
+		code += hasManyCode
+		code += '}\n\n'
+
+		return code
+	}
+}

package/src/EnumTypeSchemaGenerator.ts

@@ -0,0 +1,24 @@
+/**
+ * Enum type schema generator for bindx
+ * Generates TypeScript enum types from Contember model enums
+ */
+
+import { Model } from '@contember/schema'
+import { getEnumTypeName } from './utils'
+
+export class EnumTypeSchemaGenerator {
+	generate(model: Model.Schema): string {
+		let code = ''
+
+		for (const [enumName, values] of Object.entries(model.enums)) {
+			code += `export type ${getEnumTypeName(enumName)} = ${values.map(v => `'${v}'`).join(' | ')}\n\n`
+		}
+
+		// Export enum values as const arrays for runtime use
+		for (const [enumName, values] of Object.entries(model.enums)) {
+			code += `export const ${enumName}Values = [${values.map(v => `'${v}'`).join(', ')}] as const\n`
+		}
+
+		return code
+	}
+}

package/src/NameSchemaGenerator.ts

@@ -0,0 +1,66 @@
+/**
+ * Name schema generator for bindx
+ * Generates runtime schema names (JSON structure) for query building
+ */
+
+import { Model } from '@contember/schema'
+import { acceptEveryFieldVisitor } from '@contember/schema-utils'
+
+export interface BindxSchemaEntityNames {
+	readonly name: string
+	readonly scalars: readonly string[]
+	readonly fields: {
+		readonly [fieldName: string]:
+			| { readonly type: 'column'; readonly columnType?: string; readonly enumName?: string }
+			| { readonly type: 'one'; readonly entity: string }
+			| { readonly type: 'many'; readonly entity: string }
+	}
+}
+
+export interface BindxSchemaNames {
+	readonly entities: {
+		readonly [entityName: string]: BindxSchemaEntityNames
+	}
+	readonly enums: {
+		readonly [enumName: string]: readonly string[]
+	}
+}
+
+export class NameSchemaGenerator {
+	generate(model: Model.Schema): BindxSchemaNames {
+		return {
+			entities: Object.fromEntries(
+				Object.values(model.entities).map(entity => {
+					const fields: Record<string, BindxSchemaEntityNames['fields'][string]> = {}
+					const scalars: string[] = []
+
+					acceptEveryFieldVisitor(model, entity, {
+						visitHasOne: ctx => {
+							fields[ctx.relation.name] = {
+								type: 'one',
+								entity: ctx.targetEntity.name,
+							}
+						},
+						visitHasMany: ctx => {
+							fields[ctx.relation.name] = {
+								type: 'many',
+								entity: ctx.targetEntity.name,
+							}
+						},
+						visitColumn: ctx => {
+							scalars.push(ctx.column.name)
+							fields[ctx.column.name] = ctx.column.type === Model.ColumnType.Enum
+								? { type: 'column', columnType: ctx.column.columnType, enumName: ctx.column.columnType }
+								: { type: 'column', columnType: ctx.column.columnType }
+						},
+					})
+
+					return [entity.name, { name: entity.name, fields, scalars }]
+				}),
+			),
+			enums: Object.fromEntries(
+				Object.entries(model.enums).map(([name, values]) => [name, values]),
+			),
+		}
+	}
+}

package/src/RoleSchemaGenerator.ts

@@ -0,0 +1,219 @@
+/**
+ * Role-aware schema generator for bindx.
+ *
+ * Generates per-role entity interfaces filtered by Contember ACL read permissions.
+ * For each role, only fields with read access (true or predicate) are included.
+ */
+
+import { Model, Acl } from '@contember/schema'
+import { acceptEveryFieldVisitor } from '@contember/schema-utils'
+import { columnToTsType, getEnumTypeName } from './utils'
+
+export interface RoleSchemaGeneratorOptions {
+	/**
+	 * Whether to treat predicate-based permissions as allowed.
+	 * When true, any non-false permission allows access.
+	 * When false, only explicit `true` permissions are allowed.
+	 * Default: true
+	 */
+	allowPredicateAccess?: boolean
+}
+
+interface RoleFieldAccess {
+	/** role name → set of readable field names */
+	[role: string]: Set<string>
+}
+
+export class RoleSchemaGenerator {
+	private readonly allowPredicateAccess: boolean
+
+	constructor(options: RoleSchemaGeneratorOptions = {}) {
+		this.allowPredicateAccess = options.allowPredicateAccess ?? true
+	}
+
+	/**
+	 * Generates per-role entity types + role map types.
+	 * Returns code to be appended to entities.ts.
+	 */
+	generateRoleEntities(model: Model.Schema, acl: Acl.Schema): string {
+		const roles = this.resolveRoles(acl)
+		const roleNames = Object.keys(roles)
+
+		let code = ''
+
+		// Generate per-role entity interfaces
+		for (const roleName of roleNames) {
+			const roleAccess = roles[roleName]!
+			code += this.generateRoleEntityTypes(model, roleName, roleAccess)
+		}
+
+		// Generate RoleSchemas type map per entity
+		for (const entity of Object.values(model.entities)) {
+			const roleEntries = roleNames
+				.filter(role => roles[role]!.has(entity.name))
+				.map(role => `\treadonly ${role}: ${this.roleEntityName(role, entity.name)}`)
+				.join('\n')
+
+			if (roleEntries) {
+				code += `export interface ${entity.name}$Roles {\n${roleEntries}\n}\n\n`
+			}
+		}
+
+		// Export available roles type
+		code += `export type AvailableRoles = ${roleNames.map(r => `'${r}'`).join(' | ')}\n`
+
+		return code
+	}
+
+	/**
+	 * Generates schema.ts content using roleEntityDef.
+	 */
+	generateSchemaFile(model: Model.Schema, acl: Acl.Schema): string {
+		const roles = this.resolveRoles(acl)
+		const roleNames = Object.keys(roles)
+		const entityNames = Object.values(model.entities).map(e => e.name).sort()
+
+		// Build imports for role entity types
+		const roleTypeImports: string[] = []
+		for (const name of entityNames) {
+			const hasRoles = roleNames.some(role => roles[role]!.has(name))
+			if (hasRoles) {
+				roleTypeImports.push(`${name}$Roles`)
+			}
+		}
+
+		const entries = entityNames.map(name => {
+			const hasRoles = roleNames.some(role => roles[role]!.has(name))
+			if (hasRoles) {
+				return `\t${name}: roleEntityDef<${name}$Roles>('${name}', schemaDef),`
+			}
+			return `\t${name}: entityDef<${name}>('${name}', schemaDef),`
+		}).join('\n')
+
+		const allImports = [...entityNames, ...roleTypeImports]
+
+		return `import { entityDef, roleEntityDef } from '@contember/bindx'
+import { schemaNamesToDef } from '@contember/bindx-react'
+import type { ${allImports.join(', ')} } from './entities'
+import { schemaNames } from './names'
+
+const schemaDef = schemaNamesToDef(schemaNames)
+
+export const schema = {
+${entries}
+} as const
+`
+	}
+
+	/**
+	 * Resolves role permissions, flattening inheritance.
+	 * Returns a map: role → (entity → Set<fieldName>)
+	 */
+	private resolveRoles(acl: Acl.Schema): Record<string, Map<string, Set<string>>> {
+		const result: Record<string, Map<string, Set<string>>> = {}
+
+		for (const [roleName, rolePerms] of Object.entries(acl.roles)) {
+			// Skip implicit roles
+			if (rolePerms.implicit) continue
+
+			const entityFieldMap = new Map<string, Set<string>>()
+
+			// Collect inherited fields first
+			if (rolePerms.inherits) {
+				for (const parentRole of rolePerms.inherits) {
+					const parentFields = result[parentRole]
+					if (parentFields) {
+						for (const [entityName, fields] of parentFields) {
+							const existing = entityFieldMap.get(entityName) ?? new Set()
+							for (const field of fields) {
+								existing.add(field)
+							}
+							entityFieldMap.set(entityName, existing)
+						}
+					}
+				}
+			}
+
+			// Add own permissions
+			for (const [entityName, entityPerms] of Object.entries(rolePerms.entities)) {
+				const readPerms = entityPerms.operations.read
+				if (!readPerms) continue
+
+				const fields = entityFieldMap.get(entityName) ?? new Set<string>()
+				for (const [fieldName, perm] of Object.entries(readPerms)) {
+					if (perm === true || (this.allowPredicateAccess && perm !== false)) {
+						fields.add(fieldName)
+					}
+				}
+				if (fields.size > 0) {
+					entityFieldMap.set(entityName, fields)
+				}
+			}
+
+			result[roleName] = entityFieldMap
+		}
+
+		return result
+	}
+
+	/**
+	 * Generates per-role entity interfaces for a single role.
+	 */
+	private generateRoleEntityTypes(
+		model: Model.Schema,
+		roleName: string,
+		roleAccess: Map<string, Set<string>>,
+	): string {
+		let code = ''
+
+		for (const entity of Object.values(model.entities)) {
+			const accessibleFields = roleAccess.get(entity.name)
+			if (!accessibleFields || accessibleFields.size === 0) continue
+
+			code += this.generateRoleEntityType(model, entity, roleName, accessibleFields, roleAccess)
+		}
+
+		return code
+	}
+
+	private generateRoleEntityType(
+		model: Model.Schema,
+		entity: Model.Entity,
+		roleName: string,
+		accessibleFields: Set<string>,
+		roleAccess: Map<string, Set<string>>,
+	): string {
+		const typeName = this.roleEntityName(roleName, entity.name)
+		let code = `export interface ${typeName} {\n`
+
+		acceptEveryFieldVisitor(model, entity, {
+			visitColumn: ctx => {
+				if (!accessibleFields.has(ctx.column.name)) return
+				code += `\t${ctx.column.name}: ${columnToTsType(ctx.column)}${ctx.column.nullable ? ' | null' : ''}\n`
+			},
+			visitHasOne: ctx => {
+				if (!accessibleFields.has(ctx.relation.name)) return
+				const targetFields = roleAccess.get(ctx.targetEntity.name)
+				const targetType = targetFields && targetFields.size > 0
+					? this.roleEntityName(roleName, ctx.targetEntity.name)
+					: ctx.targetEntity.name
+				code += `\t${ctx.relation.name}: ${targetType}\n`
+			},
+			visitHasMany: ctx => {
+				if (!accessibleFields.has(ctx.relation.name)) return
+				const targetFields = roleAccess.get(ctx.targetEntity.name)
+				const targetType = targetFields && targetFields.size > 0
+					? this.roleEntityName(roleName, ctx.targetEntity.name)
+					: ctx.targetEntity.name
+				code += `\t${ctx.relation.name}: ${targetType}[]\n`
+			},
+		})
+
+		code += '}\n\n'
+		return code
+	}
+
+	private roleEntityName(roleName: string, entityName: string): string {
+		return `${entityName}$${roleName}`
+	}
+}

package/src/generate.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+/**
+ * Example script to generate bindx schema from Contember Model
+ *
+ * Usage:
+ *   bun run packages/bindx-generator/scripts/generate.ts ./path/to/model.ts ./path/to/output/dir
+ *
+ * This script demonstrates how to use the bindx generator to create
+ * TypeScript schema files from a Contember model.
+ */
+
+import { generate } from './index'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+async function main(): Promise<void> {
+	console.log('Generating bindx schema...')
+
+	const schemaFile = process.argv[2]
+	const outputPath = process.argv[3]
+
+	if (!schemaFile || !outputPath) {
+		console.error('Usage: bun run generate.ts <schema-file> <output-dir>')
+		process.exit(1)
+	}
+
+	const absoluteSchemaFile = join(process.cwd(), schemaFile)
+	const schema = (await import(absoluteSchemaFile)).default
+
+	// Generate schema files
+	const files = generate(schema.model)
+
+	// Output directory
+	const outputDir = join(process.cwd(), outputPath)
+
+	// Create output directory
+	await mkdir(outputDir, { recursive: true })
+
+	// Write files
+	for (const [filename, content] of Object.entries(files)) {
+		const filePath = join(outputDir, filename)
+		await writeFile(filePath, String(content), 'utf-8')
+		console.log(`Generated: ${filePath}`)
+	}
+
+	console.log(`\nSchema generation complete!`)
+	console.log(`\nGenerated files in: ${outputDir}`)
+	console.log('\nTo use the generated schema:')
+	console.log('  import { useEntity, Entity } from "./generated"')
+}
+
+main().catch(error => {
+	console.error('Error generating schema:', error)
+	process.exit(1)
+})

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @contember/bindx-generator
+ *
+ * Schema generator for @contember/bindx.
+ * Generates TypeScript types and runtime schema definitions from
+ * Contember Model.Schema.
+ */
+
+export { BindxGenerator, generate } from './BindxGenerator'
+export type { BindxGeneratorOptions, GeneratedFiles } from './BindxGenerator'
+
+export { EntityTypeSchemaGenerator } from './EntityTypeSchemaGenerator'
+export { EnumTypeSchemaGenerator } from './EnumTypeSchemaGenerator'
+export { NameSchemaGenerator } from './NameSchemaGenerator'
+export { RoleSchemaGenerator } from './RoleSchemaGenerator'
+export type { RoleSchemaGeneratorOptions } from './RoleSchemaGenerator'
+export type { BindxSchemaNames, BindxSchemaEntityNames } from './NameSchemaGenerator'
+
+export { columnToTsType, getEnumTypeName, capitalizeFirstLetter } from './utils'

package/src/utils.ts

@@ -0,0 +1,54 @@
+/**
+ * Utility functions for bindx schema generation
+ */
+
+import { Model } from '@contember/schema'
+
+/**
+ * Convert Contember column type to TypeScript type string
+ */
+export const columnToTsType = (column: Model.AnyColumn): string => {
+	const baseType = (() => {
+		switch (column.type) {
+			case Model.ColumnType.Enum:
+				return getEnumTypeName(column.columnType)
+			case Model.ColumnType.String:
+				return 'string'
+			case Model.ColumnType.Int:
+				return 'number'
+			case Model.ColumnType.Double:
+				return 'number'
+			case Model.ColumnType.Bool:
+				return 'boolean'
+			case Model.ColumnType.DateTime:
+				return 'string'
+			case Model.ColumnType.Time:
+				return 'string'
+			case Model.ColumnType.Date:
+				return 'string'
+			case Model.ColumnType.Json:
+				return 'JSONValue'
+			case Model.ColumnType.Uuid:
+				return 'string'
+			default:
+				((_: never) => {
+					throw new Error(`Unknown column type ${_}`)
+				})(column.type)
+		}
+	})()
+	return column.list ? `readonly ${baseType}[]` : baseType
+}
+
+/**
+ * Generate TypeScript enum type name from Contember enum name
+ */
+export const getEnumTypeName = (enumName: string): string => {
+	return `${enumName}Enum`
+}
+
+/**
+ * Capitalize first letter of a string
+ */
+export const capitalizeFirstLetter = (value: string): string => {
+	return value.charAt(0).toUpperCase() + value.slice(1)
+}