@mlagie/sql-connector 3.0.3 → 3.1.0

package/docs/QUERY.md

@@ -0,0 +1,281 @@
+# Query and condition reference
+
+## Table of contents
+
+1. [Structured filters](#structured-filters)
+2. [Values](#values)
+3. [Comparison operators](#comparison-operators)
+4. [IN and NOT IN](#in-and-not-in)
+5. [BETWEEN and NOT BETWEEN](#between-and-not-between)
+6. [NULL](#null)
+7. [AND, OR and NOT](#and-or-and-not)
+8. [Select](#select)
+9. [Group by](#group-by)
+10. [Having](#having)
+11. [Order by](#order-by)
+12. [Limit and offset](#limit-and-offset)
+13. [Joins](#joins)
+
+## Structured filters
+
+`where` and `having` accept structured objects. Raw SQL strings are rejected by the query builder.
+
+```js
+{
+  status: 'active',
+  age: { '>=': 18 },
+}
+```
+
+Fields at the same object level are combined with `AND`.
+
+## Values
+
+A scalar value means equality:
+
+```js
+{ status: 'active' }
+```
+
+Values are bound through driver parameters.
+
+`null` is special and becomes `IS NULL`:
+
+```js
+{ deleted_at: null }
+```
+
+Objects that do not contain a recognized operator are treated as values and passed to the driver.
+
+## Comparison operators
+
+Supported operators:
+
+```text
+=
+!=
+>
+<
+>=
+<=
+LIKE
+NOT LIKE
+ILIKE
+NOT ILIKE
+IN
+NOT IN
+BETWEEN
+NOT BETWEEN
+```
+
+Examples:
+
+```js
+{ age: { '>=': 18 } }
+{ email: { LIKE: '%@example.com' } }
+{ email: { 'NOT LIKE': '%@example.com' } }
+```
+
+## IN and NOT IN
+
+```js
+{ status: { IN: ['active', 'pending'] } }
+{ status: { 'NOT IN': ['deleted', 'blocked'] } }
+```
+
+Each item receives its own parameter placeholder.
+
+## BETWEEN and NOT BETWEEN
+
+```js
+{ age: { BETWEEN: [18, 65] } }
+{ age: { 'NOT BETWEEN': [18, 65] } }
+```
+
+The value is a two-element array `[min, max]`.
+
+## NULL
+
+```js
+{ deleted_at: null }
+{ deleted_at: { '=': null } }
+{ deleted_at: { '!=': null } }
+```
+
+These compile to `IS NULL` / `IS NOT NULL`.
+
+## AND, OR and NOT
+
+```js
+{
+  AND: [
+    { active: true },
+    {
+      OR: [
+        { role: 'admin' },
+        { role: 'moderator' },
+      ],
+    },
+  ],
+}
+```
+
+Negation:
+
+```js
+{
+  NOT: {
+    status: { IN: ['deleted', 'blocked'] },
+  },
+}
+```
+
+Empty logical arrays and invalid `NOT` values are rejected.
+
+## Select
+
+Supported structured select entries include:
+
+| Entry | Meaning |
+|---|---|
+| `'email'` | Column |
+| `'*'` | All columns |
+| `{ col: 'email', as: 'address' }` | Column + alias |
+| `{ sum: 'amount', as: 'total' }` | `SUM` |
+| `{ count: 'id', as: 'total' }` | `COUNT` |
+| `{ count: ['team', 'source'] }` | Multi-column count expression |
+| `{ count: { status: 'active' } }` | Conditional count |
+| `{ distinct: 'status' }` | `DISTINCT` |
+| `{ dateFormat: ['created_at', '%Y-%m'] }` | Date formatting |
+
+Example:
+
+```js
+const stats = await User.find({
+  select: [
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
+  ],
+  where: { active: true },
+});
+```
+
+## Group by
+
+`groupBy` is passed as an option to `find()`:
+
+```js
+const stats = await User.find({
+  select: [
+    'status',
+    { count: 'id', as: 'total' },
+  ],
+  groupBy: ['status'],
+});
+```
+
+Structured group items can use `col` and `dateFormat` (and the builder accepts `as`).
+
+## Having
+
+`having` filters grouped results and uses the same structured condition format as `where`:
+
+```js
+const stats = await User.find({
+  select: [
+    'status',
+    { count: 'id', as: 'total' },
+  ],
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
+});
+```
+
+The condition is applied after `GROUP BY`. Raw `HAVING` strings are rejected.
+
+## Order by
+
+`orderBy` is also part of the `find()` options and can sort by a selected column or alias:
+
+```js
+const stats = await User.find({
+  select: [
+    'status',
+    { count: 'id', as: 'total' },
+  ],
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
+  orderBy: [
+    { field: 'total', direction: 'DESC' },
+    { field: 'status', direction: 'ASC' },
+  ],
+});
+```
+
+Only `ASC` and `DESC` are accepted.
+
+## Complete example
+
+The following example combines `SELECT`, aggregation, `WHERE`, `GROUP BY`, `HAVING` and `ORDER BY` in one query:
+
+```js
+const stats = await User.find({
+  select: [
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
+  ],
+  where: {
+    active: true,
+  },
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
+  orderBy: [
+    { field: 'total', direction: 'DESC' },
+  ],
+});
+```
+
+Conceptually, this produces the following SQL shape:
+
+```sql
+SELECT status, COUNT(id) AS total, SUM(amount) AS revenue
+FROM users
+WHERE active = ?
+GROUP BY status
+HAVING total > ?
+ORDER BY total DESC
+```
+
+`WHERE` and `HAVING` values remain parameterized by the Connector.
+
+## Limit and offset
+
+```js
+{
+  limit: 50,
+  offset: 100,
+}
+```
+
+Both values must be non-negative integers. PostgreSQL uses numbered placeholders for these values.
+
+## Joins
+
+`Model.find()` currently emits an `INNER JOIN` from `join.table` and `join.on`:
+
+```js
+join: {
+  table: 'profiles',
+  on: 'users.id = profiles.user_id',
+}
+```
+
+The `on` expression is SQL text and must therefore be trusted.

package/docs/README.md

@@ -0,0 +1,20 @@
+# sql-connector documentation
+
+This directory contains the detailed reference documentation for `@mlagie/sql-connector`.
+
+## Contents
+
+| Document | Purpose |
+|---|---|
+| [Schema](./SCHEMA.md) | Types, fields, defaults, constraints and foreign keys. |
+| [Queries and conditions](./QUERY.md) | `WHERE`, `HAVING`, operators, values, aggregations, grouping, ordering and joins. |
+| [Migrations](./MIGRATIONS.md) | Planning, schema diffing, approvals, destructive changes, checksums, encryption and backups. |
+| [API](./API.md) | Public exports and method reference. |
+| [Dialects](./DIALECTS.md) | MySQL/PostgreSQL behavior and SQL generation differences. |
+| [French documentation](./fr/README_FR.md) | Documentation française. |
+
+## Documentation principles
+
+The documentation describes the behavior implemented by the current package rather than every SQL feature that exists in the SQL standard or in an individual database engine.
+
+Where an API is intentionally narrower than raw SQL, the supported structured representation is documented explicitly.

package/docs/SCHEMA.md

@@ -0,0 +1,167 @@
+# Schema reference
+
+## Table of contents
+
+1. [Schema object](#schema-object)
+2. [Field definition](#field-definition)
+3. [Types](#types)
+4. [Length, precision and scale](#length-precision-and-scale)
+5. [Defaults](#defaults)
+6. [Constraints](#constraints)
+7. [Enums](#enums)
+8. [Foreign keys](#foreign-keys)
+9. [Column renames](#column-renames)
+10. [Custom SQL](#custom-sql)
+
+## Schema object
+
+```js
+const { Schema } = require('@mlagie/sql-connector');
+
+const userSchema = new Schema({
+  id: { type: Number, primary_key: true, auto_increment: true },
+  email: { type: String, required: true, unique: true, length: 320 },
+});
+```
+
+`Schema` stores the desired field definitions in `schemaDict`.
+
+## Field definition
+
+```js
+{
+  type: String,
+  length: 255,
+  precision: 12,
+  scale: 2,
+  required: true,
+  default: 'active',
+  unique: true,
+  primary_key: false,
+  auto_increment: false,
+  enum: ['active', 'inactive'],
+  foreignKey: 'users(id)',
+  oldname: 'legacy_email',
+  customize: 'CHECK (...)'
+}
+```
+
+## Types
+
+The built-in map is:
+
+```text
+String             -> VARCHAR
+Char               -> CHAR
+Number             -> INT
+SmallInt           -> SMALLINT
+BigInt             -> BIGINT
+Decimal            -> DECIMAL
+Boolean            -> BOOLEAN
+Date               -> DATETIME
+Object             -> JSON
+Array              -> VARCHAR
+Now                -> NOW()
+Float              -> FLOAT
+Double             -> DOUBLE
+Text               -> TEXT
+Blob               -> BLOB
+Binary             -> VARBINARY
+Uuid               -> CHAR
+DateTime           -> DATETIME
+Timestamp          -> TIMESTAMP
+CurrentTimestamp   -> CURRENT_TIMESTAMP
+```
+
+JavaScript constructors `String`, `Number`, `Boolean`, `Date`, `Object` and `Array` are also accepted by the schema API.
+
+## Length, precision and scale
+
+Use `length` with `VARCHAR`, `CHAR`, `BINARY` and `VARBINARY`.
+
+Use `precision` and `scale` with `DECIMAL`:
+
+```js
+amount: {
+  type: 'DECIMAL',
+  precision: 12,
+  scale: 2,
+}
+```
+
+## Defaults
+
+Defaults may be `null`, strings, numbers, booleans, dates, objects, temporal SQL expressions or functions returning supported values.
+
+```js
+created_at: {
+  type: Date,
+  default: 'CURRENT_TIMESTAMP',
+}
+```
+
+`sqlTypeMap.CurrentTimestamp` is available as a reusable constant.
+
+## Constraints
+
+Supported field-level constraints:
+
+- `required` → `NOT NULL`;
+- `unique` → `UNIQUE`;
+- `primary_key` → `PRIMARY KEY`;
+- `auto_increment` → auto-increment / identity behavior;
+- `foreignKey` → `FOREIGN KEY`;
+- `default` → `DEFAULT`;
+- `enum` → `ENUM` where supported by the generated dialect SQL;
+- `customize` → additional SQL definition.
+
+Do not set `primary_key` and `unique` together.
+
+## Enums
+
+```js
+status: {
+  type: String,
+  enum: ['pending', 'paid', 'cancelled'],
+  default: 'pending',
+}
+```
+
+Enum values are SQL-escaped when the column definition is generated.
+
+## Foreign keys
+
+The connector accepts both forms:
+
+```js
+user_id: { type: Number, foreignKey: 'users(id)' }
+user_id: { type: Number, foreignKey: 'users.id' }
+```
+
+`Model.syncAllTables()` orders table creation according to model dependencies and rejects cycles.
+
+## Column renames
+
+Migrations use `oldname` for explicit renames:
+
+```js
+email_address: {
+  type: String,
+  oldname: 'email',
+}
+```
+
+The differ never guesses a rename from similar names.
+
+## Custom SQL
+
+```js
+amount: {
+  type: 'DECIMAL',
+  precision: 12,
+  scale: 2,
+  customize: 'CHECK (amount >= 0)',
+}
+```
+
+`customize` is appended to the generated column definition. Treat it as trusted SQL.