@softize/opus 8.6.6

package/src/dsl/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @softize/opus/dsl — Public entry.
+ */
+
+export type {
+  AstNode,
+  LiteralNode,
+  ArrayNode,
+  IdentifierNode,
+  MemberAccessNode,
+  UnaryOpNode,
+  BinaryOpNode,
+  BinaryOp,
+  InNode,
+  BetweenNode,
+  LikeNode,
+  IsNullNode,
+  FunctionCallNode,
+} from './types.ts'
+
+export { parseExpression } from './parser.ts'
+export { evalExpression, type EvalContext } from './eval.ts'
+export { compileToKysely, compileWhere, type KyselyBindings } from './kysely.ts'
+export {
+  parseLoad,
+  resolveLoadArgs,
+  type LoadSpec,
+  type LoadArg,
+} from './loads.ts'

package/src/dsl/kysely.ts

@@ -0,0 +1,230 @@
+/**
+ * @softize/opus/dsl — AST → Kysely where callback.
+ *
+ * Compila uma AST de expressão em `(eb) => Expression` consumível por
+ * `query.where(...)` do Kysely.
+ *
+ * Pra que isso valha, o DSL precisa estar no escopo da tabela (identifiers
+ * raiz são colunas; ex: `status == 'open'` vira `eb('status', '=', 'open')`).
+ *
+ * Contexto adicional (`user`, `now`, etc) é injetado via `bindings` na hora
+ * da compilação — esses identifiers viram literais resolvidos.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { AstNode } from './types.ts'
+import { parseExpression } from './parser.ts'
+
+export interface KyselyBindings {
+  /**
+   * Map de identifier raiz → valor. Quando AST referencia
+   * `user.kind`, e bindings.user = { kind: 'employee' }, o compiler
+   * inline o valor como literal.
+   */
+  [name: string]: unknown
+}
+
+interface KyselyEb {
+  // Subset usado. Tipos estrito do Kysely são complexos; usamos any onde
+  // não acrescentam segurança pro caller (Kysely valida em runtime/typecheck
+  // no consumer).
+  and: (exprs: any[]) => any
+  or: (exprs: any[]) => any
+  not: (expr: any) => any
+  (column: string, op: string, value: unknown): any
+  fn: { coalesce: (...args: any[]) => any }
+  lit: (v: unknown) => any
+}
+
+/**
+ * Compila AST → callback Kysely. Identifiers raiz desconhecidos viram
+ * referências a coluna (string). Identifiers em bindings viram literais.
+ */
+export function compileToKysely(
+  node: AstNode,
+  bindings: KyselyBindings = {},
+): (eb: any) => any {
+  return (eb: any) => compile(node, eb as KyselyEb, bindings)
+}
+
+/**
+ * Atalho pra repository: parsa a string DSL e devolve callback Kysely.
+ *
+ *   query.where(compileWhere('NOT archived', { user }))
+ *
+ * Equivale a `compileToKysely(parseExpression(src), bindings)` — existe pra
+ * que consumidores não precisem importar `parseExpression` separado.
+ */
+export function compileWhere(
+  src: string,
+  bindings: KyselyBindings = {},
+): (eb: any) => any {
+  return compileToKysely(parseExpression(src), bindings)
+}
+
+function compile(node: AstNode, eb: KyselyEb, bindings: KyselyBindings): any {
+  switch (node.kind) {
+    case 'literal':
+      return node.value
+    case 'array':
+      return node.items.map((i) => compile(i, eb, bindings))
+    case 'identifier': {
+      if (Object.prototype.hasOwnProperty.call(bindings, node.name)) {
+        return bindings[node.name]
+      }
+      // identifier raiz desconhecido → nome de coluna
+      return { __column: node.name }
+    }
+    case 'member': {
+      // a.b.c → resolve a partir do binding se existir; senão erro
+      const root = compile(node.object, eb, bindings)
+      if (
+        root !== null &&
+        typeof root === 'object' &&
+        !('__column' in (root as object))
+      ) {
+        return (root as Record<string, unknown>)[node.property]
+      }
+      throw new Error(
+        `DSL kysely: member access em coluna não suportado ('${node.property}')`,
+      )
+    }
+    case 'unary': {
+      const operand = compile(node.operand, eb, bindings)
+      /* v8 ignore next */
+      return node.op === 'NOT' ? eb.not(operand) : -(operand as number)
+    }
+    case 'binary': {
+      if (node.op === 'AND') {
+        return eb.and([
+          compile(node.left, eb, bindings),
+          compile(node.right, eb, bindings),
+        ])
+      }
+      if (node.op === 'OR') {
+        return eb.or([
+          compile(node.left, eb, bindings),
+          compile(node.right, eb, bindings),
+        ])
+      }
+      const left = compile(node.left, eb, bindings)
+      const right = compile(node.right, eb, bindings)
+      if (isColumn(left)) {
+        return eb(columnOf(left), sqlOp(node.op), right)
+      }
+      // ambos literais: avaliar direto
+      switch (node.op) {
+        case '==':
+          return left === right
+        case '!=':
+          return left !== right
+        case '<':
+          return (left as number) < (right as number)
+        case '<=':
+          return (left as number) <= (right as number)
+        case '>':
+          return (left as number) > (right as number)
+        case '>=':
+          return (left as number) >= (right as number)
+        case '+':
+          return (left as number) + (right as number)
+        case '-':
+          return (left as number) - (right as number)
+        case '*':
+          return (left as number) * (right as number)
+        case '/':
+          return (left as number) / (right as number)
+        /* v8 ignore next 2 */
+        default:
+          throw new Error(`DSL kysely: unhandled binary ${node.op as string}`)
+      }
+    }
+    case 'in': {
+      const subj = compile(node.left, eb, bindings)
+      const arr = compile(node.values, eb, bindings) as unknown[]
+      if (isColumn(subj)) {
+        return eb(columnOf(subj), node.negated ? 'not in' : 'in', arr)
+      }
+      const has = arr.includes(subj)
+      return node.negated ? !has : has
+    }
+    case 'between': {
+      const subj = compile(node.subject, eb, bindings)
+      const lo = compile(node.low, eb, bindings)
+      const hi = compile(node.high, eb, bindings)
+      if (isColumn(subj)) {
+        return eb.and([
+          eb(columnOf(subj), node.negated ? '<' : '>=', lo),
+          eb(columnOf(subj), node.negated ? '>' : '<=', hi),
+        ])
+      }
+      const within = (subj as number) >= (lo as number) && (subj as number) <= (hi as number)
+      return node.negated ? !within : within
+    }
+    case 'like': {
+      const subj = compile(node.subject, eb, bindings)
+      const pat = compile(node.pattern, eb, bindings)
+      if (isColumn(subj)) {
+        const op = node.caseInsensitive ? 'ilike' : 'like'
+        return eb(columnOf(subj), node.negated ? `not ${op}` : op, pat)
+      }
+      throw new Error('DSL kysely: LIKE em literal não suportado')
+    }
+    case 'isNull': {
+      const subj = compile(node.subject, eb, bindings)
+      if (isColumn(subj)) {
+        return eb(columnOf(subj), node.negated ? 'is not' : 'is', null)
+      }
+      /* v8 ignore next */
+      const isNullish = subj === null || subj === undefined
+      return node.negated ? !isNullish : isNullish
+    }
+    case 'call': {
+      const args = node.args.map((a) => compile(a, eb, bindings))
+      switch (node.name) {
+        case 'NOW':
+          return new Date().toISOString()
+        case 'TODAY':
+          return new Date().toISOString().slice(0, 10)
+        case 'COALESCE':
+          return eb.fn.coalesce(...args)
+        case 'LOWER':
+        case 'UPPER':
+        case 'LENGTH':
+          throw new Error(
+            `DSL kysely: function '${node.name}' precisa de mapping de coluna explícito (use eb.fn)`,
+          )
+      }
+      throw new Error(`DSL kysely: unknown function '${node.name}'`)
+    }
+  }
+}
+
+function isColumn(v: unknown): v is { __column: string } {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    '__column' in (v as object) &&
+    typeof (v as { __column: unknown }).__column === 'string'
+  )
+}
+
+function columnOf(v: { __column: string }): string {
+  return v.__column
+}
+
+function sqlOp(op: string): string {
+  switch (op) {
+    case '==':
+      return '='
+    case '!=':
+      return '!='
+    case '<':
+    case '<=':
+    case '>':
+    case '>=':
+      return op
+    default:
+      throw new Error(`DSL kysely: op ${op} não tem SQL equivalente`)
+  }
+}

package/src/dsl/loads.ts

@@ -0,0 +1,123 @@
+/**
+ * @softize/opus/dsl — Loads parser.
+ *
+ * Sintaxe simples (não usa o parser de expressão):
+ *
+ *   ticket(:id)
+ *   shipment(:shipmentId)
+ *   customer(:customerId, status="active")
+ *
+ * Resolve em { entity, args: { paramKey: inputKey | literalValue } }.
+ * Quem executa loads é o runtime (mapeia entity → repository.findX, passa
+ * args resolvidos contra input).
+ */
+
+export interface LoadSpec {
+  entity: string
+  /**
+   * Mapeia parâmetro → fonte. Se string começa com ':', é referência ao
+   * input do action (`:id` → `input.id`). Senão é literal.
+   */
+  args: Record<string, LoadArg>
+}
+
+export type LoadArg =
+  | { source: 'input'; key: string }
+  | { source: 'literal'; value: string | number | boolean | null }
+
+const LOAD_RE = /^([a-zA-Z_][a-zA-Z0-9_]*)\((.*)\)$/
+
+export function parseLoad(src: string): LoadSpec {
+  const trimmed = src.trim()
+  const m = LOAD_RE.exec(trimmed)
+  if (m === null) {
+    throw new Error(`DSL loads: invalid syntax '${src}'`)
+  }
+  const entity = m[1]!
+  const argsRaw = m[2]!.trim()
+  const args: Record<string, LoadArg> = {}
+  if (argsRaw.length > 0) {
+    const parts = splitArgs(argsRaw)
+    let idx = 0
+    for (const part of parts) {
+      const eq = part.indexOf('=')
+      if (eq === -1) {
+        // forma posicional: `:id` ou `"valor"` — chave é o primeiro arg = `id`
+        const value = parseArgValue(part.trim())
+        const key = value.source === 'input' ? value.key : `arg${idx}`
+        args[key] = value
+      } else {
+        const key = part.slice(0, eq).trim()
+        const value = parseArgValue(part.slice(eq + 1).trim())
+        args[key] = value
+      }
+      idx += 1
+    }
+  }
+  return { entity, args }
+}
+
+function splitArgs(src: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let inStr: '"' | "'" | null = null
+  let buf = ''
+  for (let i = 0; i < src.length; i += 1) {
+    const c = src[i]!
+    if (inStr !== null) {
+      buf += c
+      if (c === inStr) inStr = null
+      continue
+    }
+    if (c === '"' || c === "'") {
+      inStr = c
+      buf += c
+      continue
+    }
+    if (c === '(' || c === '[') depth += 1
+    if (c === ')' || c === ']') depth -= 1
+    if (c === ',' && depth === 0) {
+      parts.push(buf)
+      buf = ''
+      continue
+    }
+    buf += c
+  }
+  if (buf.trim().length > 0) parts.push(buf)
+  return parts
+}
+
+function parseArgValue(raw: string): LoadArg {
+  if (raw.startsWith(':')) {
+    return { source: 'input', key: raw.slice(1) }
+  }
+  if (raw.startsWith('"') || raw.startsWith("'")) {
+    return { source: 'literal', value: raw.slice(1, -1) }
+  }
+  if (raw === 'true') return { source: 'literal', value: true }
+  if (raw === 'false') return { source: 'literal', value: false }
+  if (raw === 'null') return { source: 'literal', value: null }
+  const n = Number(raw)
+  if (!Number.isNaN(n)) return { source: 'literal', value: n }
+  // Sem aspas — trata como string crua
+  return { source: 'literal', value: raw }
+}
+
+/**
+ * Resolve um LoadSpec contra `input` em args concretos.
+ * Devolve `Record<string, any>` pronto pra passar pro repository.findBy.
+ */
+export function resolveLoadArgs(
+  spec: LoadSpec,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  const resolved: Record<string, unknown> = {}
+  for (const [k, arg] of Object.entries(spec.args)) {
+    if (arg.source === 'input') {
+      resolved[k] = input[arg.key]
+    } else {
+      resolved[k] = arg.value
+    }
+  }
+  return resolved
+}