node-sqlalchemy

A minimal SQLAlchemy-like declarative schema library for TypeScript/Node.js.

This project provides a simple class-based DSL to define tabular specs (currently CSV-focused) with stable column order, required flags, descriptions, and enum constraints.

Background

This library started from a practical need in a production project.

I wanted to define table-like schemas in Node.js with an experience close to Python's SQLAlchemy style. Existing Node.js options were useful in parts, but none matched the same declarative feel for this specific use case, so I built this library as a focused solution.

At the moment, the implementation is optimized for a specific project context. The plan is to evolve it step by step into a more general-purpose and better-supported library.

Install

npm install @tcliplab/node-sqlalchemy

API

Column Types

• Text: free-form text
• Numeric: numeric value
• Enum(values: string[]): one value from a fixed list

Column

new Column(colType, {
  name: string,
  required?: boolean,
  description?: string,
})

CsvSpec

• static columns(): Column[]
  • returns all Column definitions in declaration order
• static headers(): string[]
  • returns ordered header names (Column.opts.name)

Usage

import { Column, CsvSpec, Text, Numeric, Enum } from "@tcliplab/node-sqlalchemy";

class MySpec extends CsvSpec {
  static title = new Column(new Text(), { name: "Title", required: true });
  static price = new Column(new Numeric(), { name: "Price", required: true });
  static condition = new Column(
    new Enum(["new", "used"]),
    { name: "Condition", required: true }
  );
}

console.log(MySpec.headers());
// ["Title", "Price", "Condition"]

console.log(
  MySpec.columns().map((c) => ({
    attr: c._attr,
    name: c.name,
    required: c.required,
    description: c.description,
  }))
);

Notes

• Column order is based on declaration order.
• Numeric is intentionally named to avoid collision with JS global Number naming.

Publish to npm (quick path)

1. Create an npm account: https://www.npmjs.com/signup
2. Login:

   npm login

3. Build and publish:

   npm run build
   npm publish --access public

4. Verify:

   npm view @tcliplab/node-sqlalchemy

License

MIT