Add synonym-aware name resolution to SqlFormatter with SQL-style SqlSynonym semantics and formatter-level synonym overrides

[Copilot]

SqlFormatter previously escaped object names directly, which prevented transparent use of database synonyms in an engine-agnostic way. This change adds formatter-level extension points and a built-in synonym service so aliases can be resolved during SQL name parsing/escaping.

• Formatter extension point for name resolution

  • Added SqlFormatter.resolvingName (sync event emitter) and instance access to it.
  • escapeName() and escapeEntity() now emit a resolution event before ObjectNameValidator.escape(...).
  • Event payload includes target (the formatter instance) and current name.

• Formatter-level synonym override support

  • Added optional SqlFormatter.synonyms resolver support (resolve(name)).
  • When present, formatter instance synonyms are applied first in escapeName() / escapeEntity(), before static SqlFormatter.resolvingName handlers.
  • This enables per-formatter synonym scoping while preserving global resolver extensibility.

• Map-based singleton synonym service

  • SqlSynonym now extends Map<string, string> and acts as a singleton service via SqlSynonym.getInstance().
  • Synonym operations are performed through Map instance methods (set, delete, clear, get) plus resolve.
  • SqlSynonym constructor follows Map initialization semantics and accepts optional entries (batch initialization via new SqlSynonym(entries)).
  • resolve() supports both exact and qualified-prefix replacement (e.g. Products.ProductID) using single-pass longest-prefix matching.
  • Mapping direction follows SQL synonym usage: synonym -> original object (e.g. Products -> sales.Products).

• Public API / typings

  • Exported SqlSynonym from src/index.js and src/index.d.ts.
  • Updated TypeScript declarations for:
    • SqlFormatter.resolvingName payload shape (target, name)
    • SqlFormatter.synonyms resolver property
    • SqlSynonym as a Map subclass with getInstance() access and Map-compatible constructor overloads.

• Focused behavior coverage

  • Added spec/SqlSynonym.spec.js coverage for:
    • synonym substitution in SQL SELECT formatting
    • qualified object name substitution in escapeEntity / escapeName
    • propagation to formatter subclasses (OpenDataQueryFormatter)
    • constructor-based batch initialization from entry arrays
    • SQL-style synonym direction (synonym -> original)
    • formatter instance synonym precedence over static/global resolving handlers

import { SqlFormatter, SqlSynonym } from '@themost/query';

const globalSynonyms = SqlSynonym.getInstance();
globalSynonyms.set('Products', 'sales.Products');

const formatter = new SqlFormatter();
formatter.settings.nameFormat = '`$1`';
formatter.synonyms = new SqlSynonym([
  ['Products', 'inventory.Products']
]);

formatter.escapeEntity('Products');         // `inventory`.`Products`
formatter.escapeName('Products.ProductID'); // `inventory`.`Products`.`ProductID`

[kbarbounakis]

It seems that it's better to use a different name like target instead of formatter

[Copilot]

Updated in 6e84bfb: replaced formatter with target in the resolving event payload.

[kbarbounakis]

The SqlFormatter instance is already avaiable. We don't need to pass nameFormat

[Copilot]

Updated in 6e84bfb: removed nameFormat from the event payload and now use formatter settings directly at escape-time.

[kbarbounakis]

It seems that the event type is redundant because resolvingName event is an event emittier for resolving only events of this type,

[Copilot]

Removed the redundant event type payload in da5be42. No UI changes (screenshot N/A).

[kbarbounakis]

A method for passing an array of synonyms would be very useful e.g.

SqlSynonym.add([
  [ 'object1', 'synonym1' ],
  [ 'object2', 'synonym2' ]
])

[Copilot]

Added batch array support to SqlSynonym.add() in da5be42. No UI changes (screenshot N/A).

[kbarbounakis]

It seems that SqlSynonym is a subclass of Map. It would be better to override its methods and use use Map type declarations.

[Copilot]

Refactored SqlSynonym to extend Map with overridden behavior in da5be42 (plus follow-up alignment in e6e67a1). No UI changes (screenshot N/A).

[kbarbounakis]

SqlSynonym acts like a service and it seems that it's better to use a static method like SqlSynonym.getInstance() and the a static instance of Synonym class.

[Copilot]

Added singleton access via SqlSynonym.getInstance() and static instance usage in da5be42 (hardened in 3179dfb). No UI changes (screenshot N/A).

[kbarbounakis]

It seems static methods lile add, remove, get etc are redundant. The static instance can be access using SqlSynonym.getInstance() without calling a static method.

[Copilot]

Done in cbfc2dc: removed redundant static proxy methods and now use SqlSynonym.getInstance() directly. No UI changes (screenshot N/A).

[kbarbounakis]

Let's try to remove add method to reduce complexity and update SqlSynonym constructor to follow Map type definition where new Map() can be called using an array of entries

interface MapConstructor {
    new(): Map<any, any>;
    new <K, V>(entries?: readonly (readonly [K, V])[] | null): Map<K, V>;
    readonly prototype: Map<any, any>;
}

[Copilot]

Implemented in 9f308a3: removed the custom add() method and updated SqlSynonym to support new SqlSynonym(entries) constructor usage aligned with Map initialization. No UI changes (screenshot N/A).

[kbarbounakis]

It seems that the usage of this.getSortedKeys() increases the complexitity of this method because every time that SqlSynonym should sort the keys.

[Copilot]

Implemented in 9f308a3: simplified resolve() by removing sorted-key caching and using a single-pass longest-prefix match over existing keys. No UI changes (screenshot N/A).

[kbarbounakis]

SQL synonyms are being used for simplifying SQL expressions. So, if we are using a database engine which supports schemas, we would use a synonym to declare a table in another schema e.g. sales.Products as Products. In that case the synomym is the Products and the original data object name is sales.Products. The SqlSynonym approach -and the test unit of this MR- uses the original data object name as key and the synonym as value. We should try to follow SQL synonyms usage and reverse them.

[Copilot]

Implemented in 915f1e7 (with follow-up polish in 1f63850): synonym direction is now SQL-style (synonym -> original), and tests were updated accordingly (e.g. Products -> sales.Products). No UI changes (screenshot N/A).

[kbarbounakis]

SqlFormatter should have an option to use their own SqlSynonym instance. This instance, if exists, might be used before using the static SqlFormatter.resolvingName

[Copilot]

Implemented in 176ef4e (refined in ecf410f): SqlFormatter now supports a per-instance synonyms resolver, and it is applied before static resolvingName handlers. Added coverage to verify instance-level synonyms take precedence. No UI changes (screenshot N/A).