@softize/opus 8.6.6

package/src/dsl/parser.ts

@@ -0,0 +1,423 @@
+/**
+ * @softize/opus/dsl — Tokenizer + parser de expressões.
+ *
+ * Gramática (descendente recursiva, precedência: NOT > comp > AND > OR):
+ *
+ *   expr        = orExpr
+ *   orExpr      = andExpr ('OR' andExpr)*
+ *   andExpr     = notExpr ('AND' notExpr)*
+ *   notExpr     = 'NOT' notExpr | compExpr
+ *   compExpr    = addExpr (compOp compExpr)?
+ *   compOp      = '==' | '!=' | '<' | '<=' | '>' | '>=' |
+ *                 ('NOT')? 'IN' | ('NOT')? 'BETWEEN' |
+ *                 ('NOT')? ('I')? 'LIKE' | 'IS' ('NOT')? 'NULL'
+ *   addExpr     = mulExpr (('+'|'-') mulExpr)*
+ *   mulExpr     = unary (('*'|'/') unary)*
+ *   unary       = '-' unary | primary
+ *   primary     = literal | array | functionCall | identifier ('.' ident)* | '(' expr ')'
+ *   array       = '[' (expr (',' expr)*)? ']'
+ *   functionCall= ident '(' (expr (',' expr)*)? ')'
+ *   literal     = STRING | NUMBER | 'true' | 'false' | 'null'
+ *
+ * Identifiers válidos: [a-zA-Z_][a-zA-Z0-9_]*. Mas NÃO podem ser keyword
+ * reservada (AND, OR, NOT, IN, BETWEEN, LIKE, ILIKE, IS, NULL, true, false).
+ */
+
+import type { AstNode } from './types.ts'
+
+// =============================================================================
+// Tokens
+// =============================================================================
+
+type TokenType =
+  | 'NUMBER'
+  | 'STRING'
+  | 'IDENT'
+  | 'KEYWORD'
+  | 'OP'
+  | 'PUNCT'
+  | 'EOF'
+
+interface Token {
+  type: TokenType
+  value: string
+  pos: number
+}
+
+const KEYWORDS = new Set([
+  'AND',
+  'OR',
+  'NOT',
+  'IN',
+  'BETWEEN',
+  'LIKE',
+  'ILIKE',
+  'IS',
+  'NULL',
+  'TRUE',
+  'FALSE',
+])
+
+const MULTI_CHAR_OPS = ['==', '!=', '<=', '>='] as const
+const SINGLE_CHAR_OPS = ['<', '>', '+', '-', '*', '/'] as const
+const PUNCTS = ['(', ')', '[', ']', ',', '.'] as const
+
+function tokenize(src: string): Token[] {
+  const tokens: Token[] = []
+  let i = 0
+  while (i < src.length) {
+    const c = src[i]!
+    // whitespace
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      i += 1
+      continue
+    }
+    const startPos = i
+
+    // string literals (single or double quote)
+    if (c === '"' || c === "'") {
+      const quote = c
+      i += 1
+      let val = ''
+      while (i < src.length && src[i] !== quote) {
+        if (src[i] === '\\' && i + 1 < src.length) {
+          val += src[i + 1]
+          i += 2
+        } else {
+          val += src[i]!
+          i += 1
+        }
+      }
+      if (i >= src.length) {
+        throw new Error(`DSL parse error: unterminated string at ${startPos}`)
+      }
+      i += 1 // skip closing quote
+      tokens.push({ type: 'STRING', value: val, pos: startPos })
+      continue
+    }
+
+    // numbers
+    if (c >= '0' && c <= '9') {
+      let val = ''
+      while (i < src.length && /[0-9.]/.test(src[i]!)) {
+        val += src[i]!
+        i += 1
+      }
+      tokens.push({ type: 'NUMBER', value: val, pos: startPos })
+      continue
+    }
+
+    // multi-char operators
+    let matched = false
+    for (const op of MULTI_CHAR_OPS) {
+      if (src.startsWith(op, i)) {
+        tokens.push({ type: 'OP', value: op, pos: startPos })
+        i += op.length
+        matched = true
+        break
+      }
+    }
+    if (matched) continue
+
+    // single-char operators
+    if (SINGLE_CHAR_OPS.includes(c as (typeof SINGLE_CHAR_OPS)[number])) {
+      tokens.push({ type: 'OP', value: c, pos: startPos })
+      i += 1
+      continue
+    }
+
+    // punctuation
+    if (PUNCTS.includes(c as (typeof PUNCTS)[number])) {
+      tokens.push({ type: 'PUNCT', value: c, pos: startPos })
+      i += 1
+      continue
+    }
+
+    // identifiers / keywords
+    if (/[a-zA-Z_]/.test(c)) {
+      let val = ''
+      while (i < src.length && /[a-zA-Z0-9_]/.test(src[i]!)) {
+        val += src[i]!
+        i += 1
+      }
+      const upper = val.toUpperCase()
+      if (KEYWORDS.has(upper)) {
+        tokens.push({ type: 'KEYWORD', value: upper, pos: startPos })
+      } else {
+        tokens.push({ type: 'IDENT', value: val, pos: startPos })
+      }
+      continue
+    }
+
+    throw new Error(
+      `DSL parse error: unexpected character '${c}' at position ${i}`,
+    )
+  }
+  tokens.push({ type: 'EOF', value: '', pos: src.length })
+  return tokens
+}
+
+// =============================================================================
+// Parser (recursive descent)
+// =============================================================================
+
+class Parser {
+  private pos = 0
+  constructor(private tokens: Token[]) {}
+
+  private peek(offset = 0): Token {
+    return this.tokens[this.pos + offset]!
+  }
+
+  private consume(): Token {
+    return this.tokens[this.pos++]!
+  }
+
+  private match(type: TokenType, value?: string): boolean {
+    const t = this.peek()
+    if (t.type !== type) return false
+    if (value !== undefined && t.value !== value) return false
+    return true
+  }
+
+  private expect(type: TokenType, value?: string): Token {
+    if (!this.match(type, value)) {
+      const t = this.peek()
+      throw new Error(
+        `DSL parse error: expected ${value ?? type}, got '${t.value}' at ${t.pos}`,
+      )
+    }
+    return this.consume()
+  }
+
+  parse(): AstNode {
+    const expr = this.orExpr()
+    this.expect('EOF')
+    return expr
+  }
+
+  private orExpr(): AstNode {
+    let left = this.andExpr()
+    while (this.match('KEYWORD', 'OR')) {
+      this.consume()
+      const right = this.andExpr()
+      left = { kind: 'binary', op: 'OR', left, right }
+    }
+    return left
+  }
+
+  private andExpr(): AstNode {
+    let left = this.notExpr()
+    while (this.match('KEYWORD', 'AND')) {
+      this.consume()
+      const right = this.notExpr()
+      left = { kind: 'binary', op: 'AND', left, right }
+    }
+    return left
+  }
+
+  private notExpr(): AstNode {
+    if (this.match('KEYWORD', 'NOT')) {
+      this.consume()
+      const operand = this.notExpr()
+      return { kind: 'unary', op: 'NOT', operand }
+    }
+    return this.compExpr()
+  }
+
+  private compExpr(): AstNode {
+    const left = this.addExpr()
+
+    // Detecta operadores de comparação
+    // ==, !=, <, <=, >, >=
+    if (
+      this.match('OP', '==') ||
+      this.match('OP', '!=') ||
+      this.match('OP', '<') ||
+      this.match('OP', '<=') ||
+      this.match('OP', '>') ||
+      this.match('OP', '>=')
+    ) {
+      const op = this.consume().value as
+        | '=='
+        | '!='
+        | '<'
+        | '<='
+        | '>'
+        | '>='
+      const right = this.addExpr()
+      return { kind: 'binary', op, left, right }
+    }
+
+    // IS NULL / IS NOT NULL
+    if (this.match('KEYWORD', 'IS')) {
+      this.consume()
+      let negated = false
+      if (this.match('KEYWORD', 'NOT')) {
+        this.consume()
+        negated = true
+      }
+      this.expect('KEYWORD', 'NULL')
+      return { kind: 'isNull', negated, subject: left }
+    }
+
+    // NOT IN / NOT BETWEEN / NOT LIKE / NOT ILIKE
+    let negated = false
+    if (this.match('KEYWORD', 'NOT')) {
+      const save = this.pos
+      this.consume()
+      if (
+        this.match('KEYWORD', 'IN') ||
+        this.match('KEYWORD', 'BETWEEN') ||
+        this.match('KEYWORD', 'LIKE') ||
+        this.match('KEYWORD', 'ILIKE')
+      ) {
+        negated = true
+      } else {
+        // não era NOT-de-comparison; foi unary NOT após primary? não é gramaticalmente
+        // possível aqui. Restaura.
+        this.pos = save
+      }
+    }
+
+    if (this.match('KEYWORD', 'IN')) {
+      this.consume()
+      const values = this.primary()
+      return { kind: 'in', negated, left, values }
+    }
+
+    if (this.match('KEYWORD', 'BETWEEN')) {
+      this.consume()
+      const low = this.addExpr()
+      this.expect('KEYWORD', 'AND')
+      const high = this.addExpr()
+      return { kind: 'between', negated, subject: left, low, high }
+    }
+
+    if (this.match('KEYWORD', 'LIKE') || this.match('KEYWORD', 'ILIKE')) {
+      const tok = this.consume()
+      const caseInsensitive = tok.value === 'ILIKE'
+      const pattern = this.addExpr()
+      return { kind: 'like', caseInsensitive, negated, subject: left, pattern }
+    }
+
+    return left
+  }
+
+  private addExpr(): AstNode {
+    let left = this.mulExpr()
+    while (this.match('OP', '+') || this.match('OP', '-')) {
+      const op = this.consume().value as '+' | '-'
+      const right = this.mulExpr()
+      left = { kind: 'binary', op, left, right }
+    }
+    return left
+  }
+
+  private mulExpr(): AstNode {
+    let left = this.unary()
+    while (this.match('OP', '*') || this.match('OP', '/')) {
+      const op = this.consume().value as '*' | '/'
+      const right = this.unary()
+      left = { kind: 'binary', op, left, right }
+    }
+    return left
+  }
+
+  private unary(): AstNode {
+    if (this.match('OP', '-')) {
+      this.consume()
+      return { kind: 'unary', op: '-', operand: this.unary() }
+    }
+    return this.primary()
+  }
+
+  private primary(): AstNode {
+    // STRING
+    if (this.match('STRING')) {
+      const t = this.consume()
+      return { kind: 'literal', value: t.value }
+    }
+    // NUMBER
+    if (this.match('NUMBER')) {
+      const t = this.consume()
+      const n = Number(t.value)
+      if (Number.isNaN(n)) {
+        throw new Error(`DSL parse error: invalid number '${t.value}'`)
+      }
+      return { kind: 'literal', value: n }
+    }
+    // booleans / null
+    if (this.match('KEYWORD', 'TRUE')) {
+      this.consume()
+      return { kind: 'literal', value: true }
+    }
+    if (this.match('KEYWORD', 'FALSE')) {
+      this.consume()
+      return { kind: 'literal', value: false }
+    }
+    if (this.match('KEYWORD', 'NULL')) {
+      this.consume()
+      return { kind: 'literal', value: null }
+    }
+    // array
+    if (this.match('PUNCT', '[')) {
+      this.consume()
+      const items: AstNode[] = []
+      if (!this.match('PUNCT', ']')) {
+        items.push(this.orExpr())
+        while (this.match('PUNCT', ',')) {
+          this.consume()
+          items.push(this.orExpr())
+        }
+      }
+      this.expect('PUNCT', ']')
+      return { kind: 'array', items }
+    }
+    // parenthesized
+    if (this.match('PUNCT', '(')) {
+      this.consume()
+      const inner = this.orExpr()
+      this.expect('PUNCT', ')')
+      return inner
+    }
+    // identifier / function call / member access
+    if (this.match('IDENT')) {
+      const name = this.consume().value
+      // function call?
+      if (this.match('PUNCT', '(')) {
+        this.consume()
+        const args: AstNode[] = []
+        if (!this.match('PUNCT', ')')) {
+          args.push(this.orExpr())
+          while (this.match('PUNCT', ',')) {
+            this.consume()
+            args.push(this.orExpr())
+          }
+        }
+        this.expect('PUNCT', ')')
+        return { kind: 'call', name: name.toUpperCase(), args }
+      }
+      // member access (a.b.c)
+      let node: AstNode = { kind: 'identifier', name }
+      while (this.match('PUNCT', '.')) {
+        this.consume()
+        const prop = this.expect('IDENT').value
+        node = { kind: 'member', object: node, property: prop }
+      }
+      return node
+    }
+    const t = this.peek()
+    throw new Error(
+      `DSL parse error: unexpected token '${t.value}' at ${t.pos}`,
+    )
+  }
+}
+
+// =============================================================================
+// Public
+// =============================================================================
+
+export function parseExpression(src: string): AstNode {
+  return new Parser(tokenize(src)).parse()
+}

package/src/dsl/types.ts

@@ -0,0 +1,113 @@
+/**
+ * @softize/opus/dsl — AST de expressões DSL.
+ *
+ * Mesma AST consumida por 3 compilers:
+ *   - evalExpression() — runtime boolean evaluation (autorize)
+ *   - compileToKysely() — SQL where clause builder
+ *   - compileToFilterTree() — UI filter builder (futuro)
+ *
+ * Inspirada em SQL + JS literals. Ver README do módulo pra gramática
+ * completa.
+ */
+
+// =============================================================================
+// AST nodes (discriminated union por `kind`)
+// =============================================================================
+
+export type AstNode =
+  | LiteralNode
+  | ArrayNode
+  | IdentifierNode
+  | MemberAccessNode
+  | UnaryOpNode
+  | BinaryOpNode
+  | InNode
+  | BetweenNode
+  | LikeNode
+  | IsNullNode
+  | FunctionCallNode
+
+export interface LiteralNode {
+  kind: 'literal'
+  value: string | number | boolean | null
+}
+
+export interface ArrayNode {
+  kind: 'array'
+  items: AstNode[]
+}
+
+export interface IdentifierNode {
+  kind: 'identifier'
+  name: string
+}
+
+/** `a.b.c` — encadeamento de access. */
+export interface MemberAccessNode {
+  kind: 'member'
+  object: AstNode
+  property: string
+}
+
+export interface UnaryOpNode {
+  kind: 'unary'
+  op: 'NOT' | '-'
+  operand: AstNode
+}
+
+export type BinaryOp =
+  | '=='
+  | '!='
+  | '<'
+  | '<='
+  | '>'
+  | '>='
+  | 'AND'
+  | 'OR'
+  | '+'
+  | '-'
+  | '*'
+  | '/'
+
+export interface BinaryOpNode {
+  kind: 'binary'
+  op: BinaryOp
+  left: AstNode
+  right: AstNode
+}
+
+/** `x IN (a, b, c)` — array implícito do lado direito. */
+export interface InNode {
+  kind: 'in'
+  negated: boolean
+  left: AstNode
+  values: AstNode // tipicamente ArrayNode
+}
+
+export interface BetweenNode {
+  kind: 'between'
+  negated: boolean
+  subject: AstNode
+  low: AstNode
+  high: AstNode
+}
+
+export interface LikeNode {
+  kind: 'like'
+  caseInsensitive: boolean // ILIKE
+  negated: boolean
+  subject: AstNode
+  pattern: AstNode
+}
+
+export interface IsNullNode {
+  kind: 'isNull'
+  negated: boolean // IS NOT NULL
+  subject: AstNode
+}
+
+export interface FunctionCallNode {
+  kind: 'call'
+  name: string // NOW, LOWER, COALESCE, etc
+  args: AstNode[]
+}

package/src/events/drivers/mitt.ts

@@ -0,0 +1,70 @@
+/**
+ * @softize/opus/events/mitt — in-process EventBus driver
+ *
+ * Wrappa `mitt` (200 bytes, zero-dep) implementando `EventBusAdapter`.
+ * Pra monolito / dev / testes. Distribuição cross-service usa
+ * `/redis` ou `/nats` (a virem).
+ *
+ * Pattern matching:
+ *   - Nome literal: `subscribe('deal.archived', h)` recebe só esse evento.
+ *   - Wildcard global: `subscribe('*', h)` recebe **todos** os eventos
+ *     (mitt nativo). Útil pra audit secundário, analytics fan-out.
+ *   - Padrões parciais (ex: `'crm.*'`) **não** suportados em v0 — exige
+ *     wrapper customizado. Use `*` + filtro no handler quando preciso.
+ *
+ * Uso:
+ *   import { mittEvents } from '@softize/opus/events/mitt'
+ *
+ *   const bus = mittEvents()
+ *   bus.subscribe('deal.archived', (event) => console.log(event))
+ *   createRuntime({ eventBus: bus, ... })
+ */
+
+import mitt, { type Emitter } from 'mitt'
+import type {
+  DomainEvent,
+  EventBusAdapter,
+  Unsubscribe,
+} from '../../core/index.ts'
+
+export interface MittEventsOptions {
+  /** Nome do adapter (default 'mitt'). */
+  name?: string
+}
+
+/**
+ * Map de tipos pra mitt: chave é o nome do evento, valor é `DomainEvent`.
+ * Usamos `Record<string, DomainEvent>` pra mitt aceitar qualquer string como
+ * type (não limita a um union literal).
+ */
+type EventMap = Record<string, DomainEvent>
+
+export function mittEvents(options: MittEventsOptions = {}): EventBusAdapter {
+  const { name = 'mitt' } = options
+  const emitter: Emitter<EventMap> = mitt<EventMap>()
+
+  return {
+    name,
+    kind: 'eventbus',
+
+    publish(event: DomainEvent) {
+      emitter.emit(event.type, event)
+    },
+
+    subscribe(pattern: string, listener: (event: DomainEvent) => void): Unsubscribe {
+      if (pattern === '*') {
+        const wildcardHandler = (_type: string | symbol, event: DomainEvent): void => {
+          listener(event)
+        }
+        emitter.on('*', wildcardHandler)
+        return () => emitter.off('*', wildcardHandler)
+      }
+      emitter.on(pattern, listener)
+      return () => emitter.off(pattern, listener)
+    },
+
+    healthCheck() {
+      return Promise.resolve({ ok: true })
+    },
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @softize/opus/events — shared helpers/types for event-bus drivers.
+ *
+ * Drivers (mitt, futuro: redis, nats) implementam EventBusAdapter do core.
+ * Espaço reservado pra helpers comuns (wildcard matcher universal,
+ * envelope normalization, etc).
+ */
+
+export {}

package/src/log/drivers/pino.ts

@@ -0,0 +1,57 @@
+/**
+ * @softize/opus/log/pino — Pino logger driver
+ *
+ * Adapta uma instância `pino.Logger` à interface `LoggerAdapter`.
+ *
+ * Pino assina `logger.info(obj, msg)` (objeto primeiro, mensagem depois);
+ * o LoggerAdapter assina `info(msg, meta?)`. Wrapper reordena.
+ *
+ * Uso:
+ *   import pino from 'pino'
+ *   import { pinoLogger } from '@softize/opus/log/pino'
+ *
+ *   const logger = pino({ level: 'info' })
+ *   createRuntime({ logger: pinoLogger({ logger }) })
+ */
+
+import type { LoggerAdapter } from '../../core/index.ts'
+
+/**
+ * Subset de `pino.Logger` que precisamos. Permite passar qualquer logger
+ * pino-compatível (pino, pino-pretty, custom destination).
+ */
+export interface PinoCompatible {
+  trace(obj: object, msg: string): void
+  debug(obj: object, msg: string): void
+  info(obj: object, msg: string): void
+  warn(obj: object, msg: string): void
+  error(obj: object, msg: string): void
+  fatal(obj: object, msg: string): void
+  child(bindings: object): PinoCompatible
+}
+
+export interface PinoLoggerOptions {
+  /** Instância pino (ou pino-compatível) já configurada. */
+  logger: PinoCompatible
+
+  /** Nome do adapter (default 'pino'). */
+  name?: string
+}
+
+export function pinoLogger(options: PinoLoggerOptions): LoggerAdapter {
+  return makeAdapter(options.logger, options.name ?? 'pino')
+}
+
+function makeAdapter(logger: PinoCompatible, name: string): LoggerAdapter {
+  return {
+    name,
+    kind: 'logger',
+    trace: (msg, meta) => logger.trace(meta ?? {}, msg),
+    debug: (msg, meta) => logger.debug(meta ?? {}, msg),
+    info: (msg, meta) => logger.info(meta ?? {}, msg),
+    warn: (msg, meta) => logger.warn(meta ?? {}, msg),
+    error: (msg, meta) => logger.error(meta ?? {}, msg),
+    fatal: (msg, meta) => logger.fatal(meta ?? {}, msg),
+    child: (bindings) => makeAdapter(logger.child(bindings), name),
+  }
+}

package/src/log/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @softize/opus/log — shared helpers/types for logger drivers.
+ *
+ * Drivers (pino) são thin wrappers que implementam LoggerAdapter.
+ * Espaço reservado pra helpers comuns no futuro (formatters, redactors,
+ * sampling).
+ */
+
+export {}