sql-registry

library0.4.1jsnpmunverified

sql-registry is a lightweight TypeScript/JavaScript library (v0.4.1, pre-1.0, active development) for storing SQL in structured Markdown files, binding named parameters safely, and adding controlled dynamic SQL for filters, sorting, and paging. Unlike ORMs or raw query builders, it treats SQL as a reviewable static asset with parameter metadata, dialect variants, and builder logic collocated in Markdown. It enforces named parameter binding via driver values, allowlisted sort keys, validated LIMIT/OFFSET, and static builder fragments. The library handles PostgreSQL-specific syntax and provides an SQL parameter parser. Its release cadence is irregular as it is pre-1.0, with potential breaking changes; users are advised to pin versions.

database devops

npm install sql-registry

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-REGISTRY

sql-registry

databasejavascriptv0.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SqlRegistry

✓ import { SqlRegistry } from 'sql-registry'

✗ const SqlRegistry = require('sql-registry')

ESM import is preferred; CommonJS require works but may have issues with TypeScript types.

SqlFragment

✓ import { SqlFragment } from 'sql-registry'

✗ const SqlFragment = require('sql-registry').SqlFragment

Named export; always use destructuring.

registerBuilderFragment

✓ import { registerBuilderFragment } from 'sql-registry'

Utility function for builder fragments; only needed if extending builder logic.

Shows loading a Markdown registry, building a query with named parameters, and obtaining the final SQL string and bound values.

import { SqlRegistry } from 'sql-registry'; const registry = new SqlRegistry({ dialect: 'pg' }); registry.loadFile('./sql/users.md'); const params = { name: 'john', status: 'active', sort: 'name', limit: 10, offset: 0 }; const stmt = registry.build('users.search', params); console.log(stmt.text); // Final SQL string console.log(stmt.values); // Parameter values for driver // The SQL uses named parameters like :name, :status; they are bound safely. // The builder appends WHERE clauses and sets ORDER BY / LIMIT / OFFSET.

Debug

Known issues

breakingPre-1.0 API changes: The public API, Markdown format, adapter behavior, and builder helpers may change in breaking ways.

fix

Pin the package version (e.g., "sql-registry": "0.4.1") and review release notes before upgrading.

affects: >=0.0.0 <1.0.0

gotchaNamed parameters are SQL-injection safe only if bound as driver values, but builder fragments (e.g., ORDER BY column) must be allowlisted. Dynamic SQL generation from user input without allowlist is dangerous.

fix

Always use allowlisted sort keys in the 'orderable' section and validate LIMIT/OFFSET as non-negative integers.

affects: >=0.0.0

gotchaThe Markdown registry file must be loaded with loadFile() or loadDirectory() before building queries. Missing files cause errors.

fix

Ensure the file path is correct and the registry is loaded before calling build().

affects: >=0.0.0

deprecatedThe builder function 'append' for SQL fragments is case-sensitive and may be renamed in future versions.

fix

Use the documented builder API as per the Markdown file; expect potential changes in the function signature.

affects: >=0.0.0 <1.0.0

gotchaTypeScript types are shipped but may not cover all edge cases. The library is pre-1.0, so type definitions can change.

fix

Check type compatibility after upgrades; use explicit type assertions if needed.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Registry must be loaded before building queries.

The .loadFile() or .loadDirectory() method was not called, or the file path is incorrect.

fix

Call registry.loadFile('./path/to/file.md') or registry.loadDirectory('./sql/') before registry.build('query.id', params).

Error: Unknown SQL ID 'users.search'.

The query ID does not exist in the loaded registry files. Check for typos or missing files.

fix

Verify the SQL ID in the Markdown file (## users.search) and ensure the file is loaded. Use registry.list() to see available IDs.

Error: Parameter 'name' is required but was not provided.

A required parameter defined in the Markdown (param: name:string) was not passed in the params object.

fix

Ensure all required parameters are provided. Optional parameters can be omitted but may cause builder conditions to skip.

TypeError: registry.build is not a function

The imported SqlRegistry is not instantiated correctly, or the module was imported as default instead of named export.

fix

Use: import { SqlRegistry } from 'sql-registry'; const registry = new SqlRegistry({ dialect: 'pg' });

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node