@query-graph/core 1.1.4 → 1.1.5

package/lib/authoring/primitives.js

@@ -0,0 +1,433 @@
+'use strict'
+
+const { arrayOf, configurationOf, nonEmptyString, objectOf, optionalBoolean } = require('../configuration.js')
+const { SUMMARY_FIELD_BRAND } = require('./symbols.js')
+
+const SCALAR_TYPES = new Set([
+  'boolean',
+  'int32',
+  'int64',
+  'float64',
+  'decimal',
+  'string',
+  'date',
+  'dateTime',
+  'binary',
+  'json',
+])
+const FIELD_TYPE_OPTIONS_KEYS = new Set(['nullable', 'selectable'])
+const FIELD_SPECIFICATION_KEYS = new Set(['scalarType', 'nullable', 'selectable'])
+const EXISTS_CONFIGURATION_KEYS = new Set(['from'])
+
+function fieldType(scalarType, options = {}) {
+  assertScalarType(scalarType)
+  const configuration = configurationOf('fieldType', options, FIELD_TYPE_OPTIONS_KEYS)
+  optionalBoolean(configuration.nullable, 'fieldType nullable')
+  optionalBoolean(configuration.selectable, 'fieldType selectable')
+
+  const definition = { scalarType }
+  if (configuration.nullable === true) {
+    definition.nullable = true
+  }
+  if (configuration.selectable === false) {
+    definition.selectable = false
+  }
+  return definition
+}
+
+function nullable(specification) {
+  return {
+    ...normalizeFieldSpec(specification),
+    nullable: true,
+  }
+}
+
+function hidden(specification) {
+  return {
+    ...normalizeFieldSpec(specification),
+    selectable: false,
+  }
+}
+
+function source(key, fieldSpecifications) {
+  nonEmptyString(key, 'source key')
+  objectOf('source fields', fieldSpecifications)
+
+  const fields = Object.entries(fieldSpecifications).map(([name, specification]) => ({
+    name: nonEmptyString(name, 'source field name'),
+    ...normalizeFieldSpec(specification),
+  }))
+  const sourceReference = { key, fields }
+
+  Object.defineProperty(sourceReference, 'field', {
+    enumerable: false,
+    value(name) {
+      return field(sourceReference, name)
+    },
+  })
+
+  return sourceReference
+}
+
+function field(sourceReference, name) {
+  const sourceKey = referenceName(sourceReference, 'source')
+  nonEmptyString(name, 'field name')
+
+  if (typeof sourceReference !== 'string' && !sourceReference.fields.some((candidate) => candidate.name === name)) {
+    throw new TypeError(`Source ${sourceKey} does not define field ${name}`)
+  }
+
+  return {
+    kind: 'field',
+    source: sourceKey,
+    field: name,
+  }
+}
+
+function requiredParameter(name, scalarType) {
+  return parameterDefinition(name, scalarType, true)
+}
+
+function optionalParameter(name, scalarType) {
+  return parameterDefinition(name, scalarType, false)
+}
+
+function requiredListParameter(name, scalarType) {
+  return parameterDefinition(name, scalarType, true, 'list')
+}
+
+function optionalListParameter(name, scalarType) {
+  return parameterDefinition(name, scalarType, false, 'list')
+}
+
+function param(parameterReference) {
+  if (typeof parameterReference !== 'string' && parameterReference?.shape === 'list') {
+    throw new TypeError(`List parameter ${parameterReference.name} cannot be used as a scalar expression`)
+  }
+
+  return {
+    kind: 'parameter',
+    name: referenceName(parameterReference, 'parameter'),
+  }
+}
+
+function literal(value) {
+  if (value === null) {
+    return literalExpression({ kind: 'null' })
+  }
+  if (typeof value === 'boolean') {
+    return literalExpression({ kind: 'boolean', value })
+  }
+  if (typeof value === 'string') {
+    return literalExpression({ kind: 'string', value })
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? integer(value) : decimal(value)
+  }
+
+  throw new TypeError('Literal must be null, boolean, string, or number')
+}
+
+function integer(value) {
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError('Integer literal must be a safe JavaScript integer')
+  }
+  return literalExpression({ kind: 'integer', value })
+}
+
+function decimal(value) {
+  const text = String(value)
+  if (!/^-?(?:\d+(?:\.\d*)?|\.\d+)$/.test(text)) {
+    throw new TypeError(`Invalid decimal literal ${text}`)
+  }
+  return literalExpression({ kind: 'decimal', value: text })
+}
+
+function eq(left, right) {
+  return binaryExpression('eq', left, right)
+}
+
+function neq(left, right) {
+  return binaryExpression('notEq', left, right)
+}
+
+function lt(left, right) {
+  return binaryExpression('lessThan', left, right)
+}
+
+function lte(left, right) {
+  return binaryExpression('lessThanOrEqual', left, right)
+}
+
+function gt(left, right) {
+  return binaryExpression('greaterThan', left, right)
+}
+
+function gte(left, right) {
+  return binaryExpression('greaterThanOrEqual', left, right)
+}
+
+function like(expression, pattern) {
+  return {
+    kind: 'like',
+    expression: asExpression(expression),
+    pattern: asExpression(pattern),
+  }
+}
+
+function inList(expression, values) {
+  return {
+    kind: 'in',
+    expression: asExpression(expression),
+    values: arrayOf(values, 'inList values').map(asExpression),
+  }
+}
+
+function inParameter(expression, parameterReference) {
+  if (typeof parameterReference !== 'string' && parameterReference?.shape !== 'list') {
+    throw new TypeError(`Parameter ${parameterReference?.name ?? '<unknown>'} is not a list parameter`)
+  }
+
+  return {
+    kind: 'inParameter',
+    expression: asExpression(expression),
+    parameter: referenceName(parameterReference, 'parameter'),
+  }
+}
+
+function and(...expressions) {
+  return {
+    kind: 'and',
+    expressions: expressions.map(asExpression),
+  }
+}
+
+function or(...expressions) {
+  return {
+    kind: 'or',
+    expressions: expressions.map(asExpression),
+  }
+}
+
+function not(expression) {
+  return unaryExpression('not', expression)
+}
+
+function isNull(expression) {
+  return unaryExpression('isNull', expression)
+}
+
+function isNotNull(expression) {
+  return unaryExpression('isNotNull', expression)
+}
+
+function exists(sourceReference, predicate, options) {
+  const expression = {
+    kind: 'exists',
+    source: referenceName(sourceReference, 'source'),
+  }
+
+  if (options !== undefined) {
+    const configuration = configurationOf('exists', options, EXISTS_CONFIGURATION_KEYS)
+    if (configuration.from === undefined) {
+      throw new TypeError('exists requires configuration field "from"')
+    }
+    expression.from = referenceName(configuration.from, 'source')
+  }
+
+  if (predicate !== undefined) {
+    expression.predicate = asExpression(predicate)
+  }
+
+  return expression
+}
+
+function call(name, ...arguments_) {
+  return {
+    kind: 'function',
+    name,
+    arguments: arguments_.map(asExpression),
+  }
+}
+
+function lower(expression) {
+  return call('lower', expression)
+}
+
+function upper(expression) {
+  return call('upper', expression)
+}
+
+function coalesce(first, second, ...rest) {
+  return call('coalesce', first, second, ...rest)
+}
+
+function concat(first, ...rest) {
+  return call('concat', first, ...rest)
+}
+
+function aggregate(functionName, expression) {
+  const definition = {
+    kind: 'aggregate',
+    function: functionName,
+  }
+  if (expression !== undefined) {
+    definition.expression = asExpression(expression)
+  }
+  return definition
+}
+
+function count(expression) {
+  return aggregate('count', expression)
+}
+
+function countDistinct(expression) {
+  return aggregate('countDistinct', expression)
+}
+
+function sum(expression) {
+  return aggregate('sum', expression)
+}
+
+function average(expression) {
+  return aggregate('average', expression)
+}
+
+function minimum(expression) {
+  return aggregate('minimum', expression)
+}
+
+function maximum(expression) {
+  return aggregate('maximum', expression)
+}
+
+function normalizeFieldSpec(specification) {
+  if (typeof specification === 'string') {
+    return fieldType(specification)
+  }
+  if (specification && typeof specification === 'object' && !Array.isArray(specification)) {
+    const configuration = configurationOf('field specification', specification, FIELD_SPECIFICATION_KEYS)
+    return fieldType(configuration.scalarType, {
+      nullable: configuration.nullable,
+      selectable: configuration.selectable,
+    })
+  }
+  throw new TypeError('Field specification must contain a scalar type')
+}
+
+function parameterDefinition(name, scalarType, required, shape = 'scalar') {
+  nonEmptyString(name, 'parameter name')
+  assertScalarType(scalarType)
+  const definition = { name, scalarType }
+  if (required) {
+    definition.required = true
+  }
+  if (shape === 'list') {
+    definition.shape = 'list'
+  }
+  return definition
+}
+
+function literalExpression(value) {
+  return {
+    kind: 'literal',
+    value,
+  }
+}
+
+function binaryExpression(kind, left, right) {
+  return {
+    kind,
+    left: asExpression(left),
+    right: asExpression(right),
+  }
+}
+
+function unaryExpression(kind, expression) {
+  return {
+    kind,
+    expression: asExpression(expression),
+  }
+}
+
+function asExpression(value) {
+  if (value?.[SUMMARY_FIELD_BRAND] === true) {
+    return value.expression
+  }
+  if (value && typeof value === 'object' && typeof value.kind === 'string') {
+    return value
+  }
+  return literal(value)
+}
+
+function referenceName(reference, type) {
+  if (typeof reference === 'string') {
+    return nonEmptyString(reference, `${type} name`)
+  }
+  if (type === 'source') {
+    if (reference && typeof reference.key === 'string') {
+      return nonEmptyString(reference.key, 'source key')
+    }
+    throw new TypeError('Invalid source reference')
+  }
+  if (reference && typeof reference.name === 'string') {
+    return nonEmptyString(reference.name, `${type} name`)
+  }
+  throw new TypeError(`Invalid ${type} reference`)
+}
+
+function copySource(sourceReference) {
+  return {
+    key: sourceReference.key,
+    fields: sourceReference.fields.map((fieldDefinition) => ({ ...fieldDefinition })),
+  }
+}
+
+function assertScalarType(scalarType) {
+  if (!SCALAR_TYPES.has(scalarType)) {
+    throw new TypeError(`Unknown scalar type ${scalarType}`)
+  }
+}
+
+module.exports = {
+  and,
+  asExpression,
+  average,
+  coalesce,
+  concat,
+  copySource,
+  count,
+  countDistinct,
+  decimal,
+  eq,
+  exists,
+  fieldType,
+  gt,
+  gte,
+  hidden,
+  inList,
+  inParameter,
+  integer,
+  isNotNull,
+  isNull,
+  like,
+  literal,
+  lower,
+  lt,
+  lte,
+  maximum,
+  minimum,
+  neq,
+  not,
+  nullable,
+  optionalListParameter,
+  optionalParameter,
+  or,
+  param,
+  referenceName,
+  requiredListParameter,
+  requiredParameter,
+  source,
+  sum,
+  upper,
+}

package/lib/authoring/symbols.js

@@ -0,0 +1,4 @@
+'use strict'
+
+exports.GRAPH_MODULE_BRAND = Symbol('GraphModule')
+exports.SUMMARY_FIELD_BRAND = Symbol('SummaryField')

package/{composition.js → lib/composition.js}

@@ -1,34 +1,15 @@
 'use strict'
 
+const { arrayOf, configurationOf, nonEmptyString, objectOf, optionalEnum } = require('./configuration.js')
+
 const BATCH_QUERY_KEYS = new Set(['graph', 'key'])
 const BATCH_QUERY_KEY_KEYS = new Set(['path', 'parameter'])
 const BATCH_RELATION_KEYS = new Set(['name', 'from', 'query', 'cardinality', 'parameters', 'ordering'])
 const COMPOSE_KEYS = new Set(['root', 'relations'])
+const BATCH_CARDINALITIES = new Set(['one', 'many'])
 const batchQueryBrand = Symbol('BatchQuery')
 const batchBrand = Symbol('BatchRelation')
 
-function configurationOf(factory, value, allowedKeys) {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new TypeError(`${factory} expects a configuration object`)
-  }
-
-  const unknownKeys = Reflect.ownKeys(value).filter((key) => typeof key !== 'string' || !allowedKeys.has(key))
-  if (unknownKeys.length > 0) {
-    const label = unknownKeys.length === 1 ? 'field' : 'fields'
-    const keys = unknownKeys.map((key) => JSON.stringify(String(key))).join(', ')
-    throw new TypeError(`${factory} received unknown configuration ${label} ${keys}`)
-  }
-
-  return value
-}
-
-function nonEmptyString(value, label) {
-  if (typeof value !== 'string' || value.trim() === '') {
-    throw new TypeError(`${label} must be a non-empty string`)
-  }
-  return value
-}
-
 function relationalGraph(value, label) {
   if (value === null || typeof value !== 'object' || typeof value.compose !== 'function') {
     throw new TypeError(`${label} must be a RelationalQueryGraph`)
@@ -72,17 +53,12 @@ function batchRelation(value) {
 
   const from = nonEmptyString(configuration.from, 'batchRelation.from')
   const query = batchQueryOf(configuration.query, 'batchRelation.query')
-
-  if (configuration.cardinality !== 'one' && configuration.cardinality !== 'many') {
+  optionalEnum(configuration.cardinality, BATCH_CARDINALITIES, 'batchRelation.cardinality')
+  if (configuration.cardinality === undefined) {
     throw new TypeError("batchRelation.cardinality must be 'one' or 'many'")
   }
-  if (
-    configuration.parameters !== undefined &&
-    (configuration.parameters === null ||
-      typeof configuration.parameters !== 'object' ||
-      Array.isArray(configuration.parameters))
-  ) {
-    throw new TypeError('batchRelation.parameters must be an object')
+  if (configuration.parameters !== undefined) {
+    objectOf('batchRelation.parameters', configuration.parameters)
   }
   if (configuration.ordering !== undefined) {
     nonEmptyString(configuration.ordering, 'batchRelation.ordering')
@@ -102,11 +78,9 @@ function batchRelation(value) {
 function composeGraph(value) {
   const configuration = configurationOf('composeGraph', value, COMPOSE_KEYS)
   const root = relationalGraph(configuration.root, 'composeGraph.root')
-  if (!Array.isArray(configuration.relations)) {
-    throw new TypeError('composeGraph.relations must be an array')
-  }
+  const relations = arrayOf(configuration.relations, 'composeGraph.relations')
 
-  return configuration.relations.reduce((graph, relation, index) => {
+  return relations.reduce((graph, relation, index) => {
     if (relation?.[batchBrand] !== true) {
       throw new TypeError(`composeGraph.relations[${index}] must be created by batchRelation`)
     }

package/lib/configuration.js

@@ -0,0 +1,66 @@
+'use strict'
+
+function objectOf(label, value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`)
+  }
+  return value
+}
+
+function configurationOf(factory, value, allowedKeys) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${factory} expects a configuration object`)
+  }
+
+  const unknownKeys = Reflect.ownKeys(value).filter((key) => typeof key !== 'string' || !allowedKeys.has(key))
+  if (unknownKeys.length > 0) {
+    const label = unknownKeys.length === 1 ? 'field' : 'fields'
+    const keys = unknownKeys.map((key) => JSON.stringify(String(key))).join(', ')
+    throw new TypeError(`${factory} received unknown configuration ${label} ${keys}`)
+  }
+
+  return value
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${label} must be a non-empty string`)
+  }
+  return value
+}
+
+function optionalBoolean(value, label) {
+  if (value !== undefined && typeof value !== 'boolean') {
+    throw new TypeError(`${label} must be a boolean`)
+  }
+  return value
+}
+
+function optionalEnum(value, allowedValues, label) {
+  if (value !== undefined && !allowedValues.has(value)) {
+    const choices = [...allowedValues].map((choice) => JSON.stringify(choice)).join(' or ')
+    throw new TypeError(`${label} must be ${choices}`)
+  }
+  return value
+}
+
+function arrayOf(value, label) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} must be an array`)
+  }
+  return value
+}
+
+function optionalArray(value, label) {
+  return value === undefined ? undefined : arrayOf(value, label)
+}
+
+module.exports = {
+  arrayOf,
+  configurationOf,
+  nonEmptyString,
+  objectOf,
+  optionalArray,
+  optionalBoolean,
+  optionalEnum,
+}

package/native.d.ts

@@ -0,0 +1,98 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class CompiledQueryPlan {
+  get root(): CompiledSqlStatement
+  get batches(): Array<CompiledBatchStep>
+  compileBatch(name: string, keys: readonly unknown[]): CompiledSqlStatement
+}
+
+export declare class ComposedQueryGraph {
+  get name(): string
+  withBatchRelation(graph: RelationalQueryGraph, relation: import('./dsl.js').BatchRelationWire): ComposedQueryGraph
+  compileSqlServerPlan(
+    operation: import('./dsl.js').QueryOperation,
+    options?: import('./dsl.js').SqlServerCompileOptions,
+  ): CompiledQueryPlan
+  compileOraclePlan(
+    operation: import('./dsl.js').QueryOperation,
+    options?: import('./dsl.js').OracleCompileOptions,
+  ): CompiledQueryPlan
+}
+
+export declare class QueryGraph {
+  get name(): string
+  get root(): string
+  get sourceCount(): number
+  get relationCount(): number
+  hasSource(source: string): boolean
+  hasField(source: string, field: string): boolean
+  hasParameter(parameter: string): boolean
+  hasRelation(relation: string): boolean
+  selectableFields(): Array<string>
+  withRelationalMapping(mapping: import('./dsl.js').RelationalMapping): RelationalQueryGraph
+  withRelationalMappings(mappings: readonly import('./dsl.js').RelationalMapping[]): RelationalQueryGraph
+}
+
+export declare class RelationalQueryGraph {
+  get name(): string
+  compose(): ComposedQueryGraph
+  compileSqlServer(
+    operation: import('./dsl.js').QueryOperation,
+    options?: import('./dsl.js').SqlServerCompileOptions,
+  ): CompiledSqlStatement
+  compileOracle(
+    operation: import('./dsl.js').QueryOperation,
+    options?: import('./dsl.js').OracleCompileOptions,
+  ): CompiledSqlStatement
+}
+
+export interface CompiledBatchStep {
+  name: string
+  parentKey: string
+  childKey: string
+  keyParameter: string
+  parameters: Readonly<Record<string, unknown>>
+  cardinality: import('./dsl.js').BatchCardinality
+  parentKeyInjected: boolean
+  childKeyInjected: boolean
+}
+
+export interface CompiledSqlColumn {
+  name: string
+  path: string
+  scalarType: import('./dsl.js').ScalarType
+  nullable: boolean
+  relations: Array<string>
+}
+
+export interface CompiledSqlObject {
+  path: string
+  presenceColumn: string
+}
+
+export interface CompiledSqlRelation {
+  name: string
+  from: string
+  to: string
+  cardinality: import('./dsl.js').RelationCardinality
+  required: boolean
+}
+
+export interface CompiledSqlStatement {
+  sql: string
+  bindings: Array<SqlBinding>
+  columns: Array<CompiledSqlColumn>
+  objects: Array<CompiledSqlObject>
+  relations: Array<CompiledSqlRelation>
+}
+
+export declare function registerDefinition<const Definition extends import('./dsl.js').GraphDefinitionInput>(
+  definition: import('./dsl.js').ExactGraphDefinitionInput<Definition>,
+): import('./dsl.js').QueryGraph<Definition>
+
+export interface SqlBinding {
+  name: string
+  parameter: string
+  scalarType: import('./dsl.js').ScalarType
+  index?: number
+}