TypeScript Types Reference

This page provides type definitions for ActiveQL's main configuration interfaces in table format for easy reference.

Core Configuration Types

RuntimeConfig

Configuration for the ActiveQL Runtime:

Property	Type	Default	Description
domainGraph	`DomainGraph`	required	Domain graph from DomainGraphBuilder
name	`string`	`'ActiveQL'`	Name of this Runtime (for logging)
environment	`'development'` \| `'test'` \| `'stage'` \| `'production'`	`'development'`	Runtime environment
dataStore	`() => Promise<DataStore>`	SQLite	Factory method for DataStore implementation
fileHandler	`() => FileHandler`	`ReferenceFileHandler`	Factory method for FileHandler implementation
beforeInit	`(runtime: Runtime) => void \| Promise<void>`		Callback before Runtime initialization
afterInit	`(runtime: Runtime) => void \| Promise<void>`		Callback after Runtime initialization
localeFn	`(req: IncomingMessage) => string`	`() => 'en'`	Determine locale from request
entity	`(config: EntityConfig) => Entity`		Custom Entity factory
operation	`(config: OperationType) => Operation`		Custom Operation factory
entityResolver	`(config: EntityConfig) => EntityResolver`		Custom EntityResolver factory
entityAccessor	`(config: EntityConfig) => EntityAccessor`		Custom EntityAccessor factory
entityManager	`(config: EntityConfig) => EntityManager`		Custom EntityManager factory
pubsub	`PubSubEngine`		PubSub engine for subscriptions
schemaBuilder	`SchemaBuilder[]`		Additional schema builders
featureToggle	`{[name: string]: boolean \| Function}`		Feature toggle configuration
seedMutation	`QueryMutationConfig`		Custom seed mutation config
generateTypesMap	`boolean`	`false`	Generate TypeScript types map

DomainConfiguration

The main configuration object describing your API domain:

Property	Type	Description
entity	`{[name: string]: EntityConfig}`	Entity definitions
enum	`{[name: string]: string[] \| EnumConfig}`	Enum definitions
type	`{[name: string]: TypeConfig}`	Custom type definitions
operation	`{[name: string]: OperationType}`	Operation definitions
query	`{[name: string]: QueryMutationConfig}`	Custom query definitions
mutation	`{[name: string]: QueryMutationConfig}`	Custom mutation definitions
subscription	`{[name: string]: SubscriptionConfig}`	Custom subscription definitions
decisionTable	`{[name: string]: DecisionTableConfig}`	Decision table definitions
restCall	`{[name: string]: RestCallConfig}`	REST call integrations
action	`{[name: string]: ActionConfig}`	Scheduled actions
attributeShortcuts	`{[name: string]: AttributeConfig}`	Reusable attribute configs
defaults	`object`	Default configs for entities, operations, etc.
mcp	`MCPServerConfig`	NEW: Model Context Protocol integration
realm	`string`	Realm for multi-tenant support
init	`(runtime: Runtime) => void \| Promise<void>`	Runtime initialization callback
extendSchema	`(runtime: Runtime) => string`	Extend GraphQL schema
contextFn	`(req, runtime) => any`	Custom context function
expressionContextFn	`(runtime) => any`	Expression context function
route	`{[path: string]: RouteConfig}`	Express routes

EntityConfig

Configuration for an entity:

Property	Type	Description
attributes	`{[name: string]: string \| AttributeConfig}`	Entity attributes
assocTo	`string \| string[] \| AssocToType`	Has-one relationships
assocToMany	`string \| string[] \| AssocToManyType`	Has-many relationships
assocFrom	`string \| string[]`	Reverse has-many relationships
assocBy	`string \| string[]`	Reverse has-one relationships
indication	`string \| string[] \| Function`	Display text for items
ui	`EntityUIConfig`	Admin UI configuration
permissions	`EntityPermissionsType`	Role-based permissions
validation	`ValidationType`	Validation function or config
stateEngine	`EntityStateEngineConfig`	NEW: State machine configuration
timeValidation	`TimeValidationType`	Time interval validation
seeds	`number \| SeedConfig`	Seed data configuration
typesQuery	`boolean`	Enable/disable types query
typeQuery	`boolean`	Enable/disable type query
createMutation	`boolean`	Enable/disable create mutation
updateMutation	`boolean`	Enable/disable update mutation
deleteMutation	`boolean`	Enable/disable delete mutation
statsQuery	`boolean`	Enable/disable stats query
implements	`string \| string[]`	Interface implementation
abstract	`boolean`	Mark as abstract entity
interface	`boolean`	Mark as interface entity
union	`string[]`	Union type members
realm	`string`	Entity realm
collection	`string`	Database collection name
path	`string`	UI path
beforeSave	`(item, runtime) => any`	Before save hook
afterSave	`(item, runtime) => any`	After save hook
beforeDelete	`(item, runtime) => any`	Before delete hook
afterDelete	`(id, runtime) => any`	After delete hook
jsonResult	`boolean \| Function`	Custom JSON transformation

AttributeConfig

Configuration for an entity attribute:

Property	Type	Default	Description
type	`string`	required	String, Int, Float, Boolean, Date, DateTime, JSON, File, or custom
list	`boolean`	`false`	Is array/list type
required	`boolean`	`false`	Is required field
unique	`boolean`	`false`	Must be unique
createInput	`boolean`	`true`	Include in create input
updateInput	`boolean`	`true`	Include in update input
queryBy	`boolean`	`false`	Generate queryBy query
filterable	`boolean`	`true`	Can be used in filter
sortable	`boolean`	`true`	Can be used for sorting
validation	`AttributeValidationType`		Validation rules
defaultValue	`any \| Function`		Default value or function
timeSeries	`TimeSeriesConfig`		Time-dependent values
description	`string`		Schema documentation

EntityStateEngineConfig (NEW)

State machine configuration for entities:

Property	Type	Default	Description
stateAttribute	`string`	`'state'`	Attribute holding the state
initial	`string`		Initial state value
expose	`boolean`	`true`	Generate state query and mutation
transitionEnumName	`string`	auto	Name for transition enum
stateQueryName	`string`	auto	Name for state query
stateMutationName	`string`	auto	Name for state transition mutation
transition	`{[name: string]: StateEngineTransition}`		Transition definitions
observe	`EntityStateEngineObserve[]`		Auto-trigger transitions
context	`EntityStateEngineContext`		Context variables

StateEngineTransition

Property	Type	Description
from	`string \| string[]`	Source state(s)
to	`string`	Target state
condition	`string \| Function`	FEEL expression or function
decisionTable	`string`	Reference to decision table
beforeTransition	`(item, runtime) => any`	Before transition hook
afterTransition	`(item, runtime) => any`	After transition hook

EntityStateEngineObserve

Property	Type	Description
mutation	`string`	Watch this mutation
entity	`string`	Watch this entity
when	`string \| Function`	Condition to trigger
transition	`string`	Transition to perform

OperationType

Configuration for a complex operation:

Property	Type	Description
input	`{[name: string]: string \| OperationInputConfig}`	Input field definitions
validation	`OperationValidationType`	Validation config
dispositions	`{[path: string]: any \| Function}`	Data transformations
onContextCreate	`(context) => any`	On context creation
beforeValidation	`(context) => any`	Before validation
beforeSave	`(context) => any`	Before save
afterSave	`(context) => any`	After save
buildResult	`(context) => any`	Build result
afterBuildResult	`(context) => any`	After build result
resultType	`string`	GraphQL result type
resultConfig	`ResultConfig`	Result configuration
permissions	`OperationPermissionsType`	Permissions
graphqlType	`'query' \| 'mutation'`	GraphQL operation type
description	`string`	Schema documentation

OperationInputConfig

Property	Type	Description
type	`string`	Input type
required	`boolean`	Is required
list	`boolean`	Is array/list
cardinality	`CardinalityType`	NEW: Min/max constraints
readonly	`boolean`	NEW: Read-only field
validation	`InputValidationType`	Validation rules
ref	`string`	Entity reference shortcut
assoc	`OperationType`	Nested operation

Admin UI Configuration Types

ActiveAdminConfig

Main configuration for the Admin UI:

Property	Type	Default	Description
path	`string`	`'/active-admin'`	Base path for admin UI
title	`string \| Function`	`'ActiveQL Admin'`	UI title
entities	`{[name: string]: EntityUIConfiguration}`		Entity UI configs
menu	`ActiveAdminMenuConfig`	auto	Menu configuration
login	`(runtime, props) => Promise<{token?}>`		Login function
principalForToken	`(token, runtime) => Promise<Principal>`		Token to principal
pageSize	`number`	`20`	Default page size
assocFromTableSize	`number`	`10`	AssocFrom table size
selectVsSearchThreshold	`number`	`10`	Dropdown vs search threshold
routes	`ActiveUIRoutes`		Custom routes
controllerFn	`ControllerFactoryFn`		Custom controller factory
viewPath	`string`		Custom view templates path
content	`ActiveAdminContent`		Custom content blocks
locale	`string`	`'en'`	Default locale
i18n	`I18nDictionary`		Internationalization dictionary
i18nInit	`(activeAdmin) => void \| Promise<void>`		I18n initialization
i18nLookup	`(activeAdmin, path, principal?) => string`		I18n lookup function
data	`{[name: string]: DataFn}`		NEW: Custom data functions
saveFiles	`(entityUI, item, files) => Promise<void>`		File save handler
getFileUrl	`(entityUI, url) => Promise<string>`		File URL resolver
uploadTempPath	`string`		Temp upload path
init	`(activeAdmin) => void \| Promise<void>`		Initialization callback
entityPath	`(params) => string \| undefined`		Custom entity path generator

EntityUIConfiguration

Configuration for how an entity appears in the Admin UI:

Property	Type	Description
collectionTitle	`string \| Function`	Collection page title
itemTitle	`string \| Function`	Item page title
fields	`{[name: string]: false \| FieldUIConfiguration}`	Field configurations
index	`EntityUIIndexConfiguration`	Index/list page config
show	`EntityUIShowConfiguration`	Detail/show page config
new	`EntityUINewConfiguration`	New/create page config
edit	`EntityUIEditConfiguration`	Edit page config
assocFrom	`EntityUIAssocFromConfiguration`	Reverse association config

EntityUIIndexConfiguration

Property	Type	Description
fields	`string[]`	Fields to show in list
actions	`{[name: string]: EntityActionConfig}`	Custom actions

EntityUIShowConfiguration

Property	Type	Description
fields	`string[]`	Fields to show in detail view
actions	`{[name: string]: EntityActionConfig}`	Custom actions
content	`ContentBlockConfig[]`	NEW: Custom content blocks (maps, templates)

EntityActionConfig

Property	Type	Description
label	`string \| Function`	Action label
confirm	`boolean \| string`	Confirmation prompt
newWindow	`boolean`	Open in new window
action	`string \| Function`	Action handler

ContentBlockConfig (NEW)

Property	Type	Description
title	`string \| Function`	Block title
content	`(params) => Promise<string \| RenderContent>`	Content renderer

RenderContent can be:

{ template: string, props?: object } - Template component
{ map: { latitude: number, longitude: number } } - Map component

FieldUIConfiguration

Configuration for individual fields:

Property	Type	Description
label	`string \| Function`	Field label
hint	`string \| Function`	Field hint text
value	`(params) => any`	Extract display value
formValue	`(params) => any`	Extract form value
render	`(params) => string`	Render to HTML
formPartial	`(fieldUI) => string`	Form partial template path

ActiveAdminMenuConfig (NEW)

Menu configuration including built-in menus:

Property	Type	Description
Developer	`DeveloperMenu \| false`	NEW: Developer tools menu
QueryMutation	`MenuType \| MenuTypeFn \| false`	NEW: Auto-generated query/mutation menu
Entities	`EntityMenu \| EntityMenuFn \| false`	NEW: Entity navigation menu
Extra	`{[name: string]: MenuType \| MenuTypeFn}`	Custom menu groups

DeveloperMenu (NEW)

Property	Type	Description
seed	`MenuAction \| false`	Seed database action
graphql	`MenuAction \| false`	GraphQL Studio link
swagger	`MenuAction \| false`	Swagger/REST API docs link
plantuml	`MenuAction \| false`	Entity diagram link
repository	`MenuAction \| false`	Repository link
configuration	`MenuAction \| false`	Show configuration link

MenuAction

Property	Type	Description
label	`string`	Menu item label
path	`string`	Navigation path
newWindow	`boolean`	Open in new window
confirm	`boolean \| string`	Confirmation prompt
action	`(params) => Promise<MenuActionResult>`	Action handler

DataStore Types

DataStore (Abstract)

Key methods:

Method	Parameters	Returns	Description
init	`(domainGraph)`	`Promise<void>`	Initialize datastore
beginTransaction	`()`	`Promise<void>`	Start transaction
commitTransaction	`()`	`Promise<void>`	Commit transaction
rollbackTransaction	`()`	`Promise<void>`	Rollback transaction
create	`(entity, attrs)`	`Promise<EntityItem>`	Create entity item
findById	`(entity, id)`	`Promise<EntityItem>`	Find by ID
findByIds	`(entity, ids)`	`Promise<EntityItem[]>`	Find by IDs
update	`(entity, attrs)`	`Promise<EntityItem>`	Update entity item
delete	`(entity, id)`	`Promise<void>`	Delete entity item
truncate	`(entity)`	`Promise<void>`	Delete all items
findByExpression	`(entity, expression, sort?, paging?)`	`Promise<EntityItem[]>`	Complex queries
findByAttribute	`(entity, attrValue, attrName?)`	`Promise<EntityItem>`	Find by attribute
findByFilter	`(entity, filter)`	`Promise<EntityItem[]>`	Find by filter
getEntityStats	`(entity, filter?)`	`Promise<EntityStats>`	Get statistics
getFilterType	`(type)`	`GraphQLInputType`	Get filter type

PgDataStoreOptions

PostgreSQL DataStore configuration:

Property	Type	Description
indexAttributes	`string[]`	Attributes to index
maxPageSize	`number`	Maximum page size
createEntityViews	`boolean`	Create SQL views for entities
dropAllViews	`boolean`	Drop all views before creating
supressIndexWarning	`boolean`	Suppress index warnings
...ClientConfig	various	PostgreSQL connection config (host, port, user, password, database, ssl, etc.)

MCP Integration Types (NEW)

MCPServerConfig

Model Context Protocol configuration:

Property	Type	Description
server	`(runtime) => McpServer`	Custom MCP server
asStreamableHttp	`boolean`	Use HTTP transport
tool	`{[name: string]: MCPResolveFn \| MCPToolConfig}`	Tool definitions
resource	`{[name: string]: MCPResourceConfig}`	Resource definitions
systemPrompt	`string`	System prompt for AI

MCPToolConfig

Property	Type	Description
description	`string`	Tool description
inputSchema	`object`	JSON schema for inputs
resolve	`MCPResolveFn`	Tool resolver function

MCPResourceConfig

Property	Type	Description
description	`string`	Resource description
mimeType	`string`	Resource MIME type
resolve	`(runtime) => Promise<MCPResourceResult>`	Resource resolver