ts-prorm-orm 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,101 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1]
+
+### Fixed
+
+- `EagerLoadError` and `UnsupportedSchemaObjectError` were not exported from the
+  package root, so callers could not catch by name the errors that `include` and
+  the schema-object methods actually throw. Both are now exported, along with the
+  schema-object SQL builders and their option types (the two whose names already
+  existed in `./types` are aliased as `CreateSequenceOptions` and
+  `CreatePolicyOptions` rather than shadowing them). A test now pins the public
+  error surface.
+
+## [1.2.0]
+
+### Fixed — relations
+
+- **Eager-load failures are no longer swallowed.** `include` caught every error
+  and reported an empty result, so a typo'd alias, a missing foreign key column,
+  an unresolvable through model and a genuinely childless parent were
+  indistinguishable. Failures now raise `EagerLoadError`; unknown or ambiguous
+  associations raise `AssociationError` before any query runs.
+- **`hasOne` inferred its foreign key from the wrong model.** `User.hasOne(Profile)`
+  means `profiles.userId`; it produced `profileId`, a column that is never
+  populated, so the association always resolved to null.
+- **One eager-loader instead of two.** `prorm.define()` and the class-based
+  `Model` API each had their own copy and they had drifted — the `model.ts` copy
+  treated `belongsTo` like `hasMany` and skipped `belongsToMany` entirely.
+- **Ambiguous includes are reported.** Two associations to the same model (e.g.
+  `author` and `editor`) previously bound to whichever was registered first.
+- **Composite foreign keys work.** Array `foreignKey` values were silently
+  dropped; they now emit a table-level `FOREIGN KEY` constraint.
+- **Synthesized foreign key columns match the referenced key's type** instead of
+  being hardcoded `INTEGER`, which broke UUID and STRING primary keys.
+- **Decorator associations bind regardless of registration order**, and a target
+  that is never registered fails `sync()` by name rather than silently omitting
+  the constraint.
+- Association `scope` is now applied, by both `include` and the generated getters.
+
+### Fixed — core
+
+- **`instance.save()` was broken for every model.** It swept internal
+  bookkeeping (`_previousDataValues`, `_changed`) into the UPDATE, so
+  `row.field = x; await row.save()` failed with `no such column`.
+- **Attribute decorators are order-independent.** `@Column` replaced the whole
+  attribute entry, and stacked decorators apply bottom-up, so the documented
+  ordering discarded `@PrimaryKey` and `@AutoIncrement` — decorator-defined
+  models were getting tables with no primary key.
+- **Auto-increment keys no longer fail their own INSERT**; create-time
+  validation exempts them and columns with a default.
+- **`count()` issues a real aggregate.** It previously fetched every matching
+  row (eager-loading its associations) and took `.length`, and discarded
+  `distinct`, `col` and `group`.
+- **Default `sync()` no longer creates a duplicate table.** Two of six table-name
+  derivations omitted pluralization, so `define('User')` + `sync()` created an
+  empty `User` beside `users` on every call.
+- `sync()` creates tables in foreign-key dependency order.
+- `findOrCreate` no longer inserts operator objects from `where`, and treats a
+  unique violation as a lost race.
+- SQLite emitted `REFERENCES "users""id"` without parentheses in table-level
+  constraints.
+- A table-level composite `PRIMARY KEY` no longer also gets an injected `id`.
+
+### Added
+
+- **`@ExternalField`** — model fields whose contents live in an object or
+  key-value store while the row lives in the database. Register a store with
+  `prorm.registerStore()`; S3, MinIO, R2, GCS, Azure Blob and Redis are
+  supported directly, with their differing APIs normalized internally.
+- **`required` / `include.where` filter parent rows**, applied before
+  `LIMIT`/`OFFSET` so pagination is correct, and composing through nesting.
+- **Schema objects through the ORM**: `createSequence`, `createTrigger`,
+  `enableRowLevelSecurity`, `createPolicy` and `createFullTextIndex` on
+  `QueryInterface`, raising `UnsupportedSchemaObjectError` naming the
+  alternative where a database has no equivalent.
+- **`sync()` applies annotation DDL** — `@View`, `@MaterializedView`, `@Trigger`,
+  and `@Procedure`/`@SqlFunction` via `prorm.registerProcedures()`.
+- **`literalExpr(sql, bindings)`** substitutes values through each dialect's
+  escaping, so the escape hatch is no longer string concatenation.
+
+### Removed
+
+- The orphaned parallel `@HasOne`/`@HasMany`/`@BelongsTo`/`@BelongsToMany` under
+  `src/decorators/`. They stored metadata that `addModel()` never read, so which
+  implementation an import resolved to decided whether the association existed.
+  The wired versions in `src/models/decorators.ts` are unchanged.
+
+### Packaging
+
+- `prepublishOnly` now runs `check:package`, which fails the publish if `dist/`
+  contains no declarations or a declared entry point is missing. **1.1.0 shipped
+  zero `.d.ts` files** despite declaring `types`, leaving every TypeScript
+  consumer without types.
+- Jest no longer scans stale worktrees under `.claude/`, which made `npm test`
+  (and therefore `npm publish`) fail.
+
 ## [Unreleased]
 
 ### Comprehensive Feature Reference

package/README.md

@@ -1,18 +1,27 @@
-# prorm
+# ts-prorm-orm
 
-[![npm version](https://img.shields.io/npm/v/@mstone6969/prorm.svg?logo=npm)](https://www.npmjs.com/package/@mstone6969/prorm)
-[![npm downloads](https://img.shields.io/npm/dm/@mstone6969/prorm.svg)](https://www.npmjs.com/package/@mstone6969/prorm)
-[![license](https://img.shields.io/npm/l/@mstone6969/prorm.svg)](./LICENSE)
+[![npm version](https://img.shields.io/npm/v/ts-prorm-orm.svg?logo=npm)](https://www.npmjs.com/package/ts-prorm-orm)
+[![npm downloads](https://img.shields.io/npm/dm/ts-prorm-orm.svg)](https://www.npmjs.com/package/ts-prorm-orm)
+[![license](https://img.shields.io/npm/l/ts-prorm-orm.svg)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![pipeline status](https://gitlab.com/Malcolmston/prod-orm/badges/main/pipeline.svg)](https://gitlab.com/Malcolmston/prod-orm/-/pipelines)
 
 A TypeScript ORM supporting multiple database dialects with full TypeScript support.
 
-> Published on npm as **[`@mstone6969/prorm`](https://www.npmjs.com/package/@mstone6969/prorm)** — `npm install @mstone6969/prorm`
+> Published on npm as **[`ts-prorm-orm`](https://www.npmjs.com/package/ts-prorm-orm)** — `npm install ts-prorm-orm`
 
 ## Features
 
-- **Multi-database support**: 14 dialects — SQLite, MySQL, PostgreSQL, MariaDB, Oracle, MSSQL, CockroachDB, Amazon Redshift, IBM Db2, Snowflake, ClickHouse, DuckDB, SAP HANA, Google Cloud Spanner
+- **Multi-database support**: 27 SQL dialects. Core implementations for SQLite,
+  PostgreSQL, MySQL, MariaDB, Oracle, MSSQL, CockroachDB, Amazon Redshift, IBM Db2,
+  Snowflake, ClickHouse, DuckDB, SAP HANA and Google Cloud Spanner; Postgres-derived
+  support for TimescaleDB, Greenplum, YugabyteDB, Vertica, Trino, Exasol, CrateDB,
+  QuestDB and Firebird; MySQL-derived for TiDB, SingleStore and Databricks; and
+  Turso/libSQL on SQLite. See [Supported Dialects](#supported-dialects) for what is
+  verified against a real engine.
+- **Relations without SQL**: `hasOne`/`hasMany`/`belongsTo`/`belongsToMany` via
+  methods or decorators, eager loading with `include`, and `required` / `include.where`
+  to filter parents by their children — applied before `LIMIT`, so pagination is correct
 - **TypeScript-first**: Full TypeScript support with decorators
 - **CRUD operations**: Full query builder with associations, scopes, transactions
 - **Migrations**: Database versioning and seeding
@@ -20,13 +29,16 @@ A TypeScript ORM supporting multiple database dialects with full TypeScript supp
 - **Validation**: Built-in and custom validators
 - **Stored Procedures**: Create and call stored procedures (across supported dialects)
 - **Triggers**: Database triggers with FOR EACH ROW and WHEN clauses (across supported dialects)
-- **Sequences**: Sequence support across all dialects
+- **Sequences**: `createSequence()` on PostgreSQL, MariaDB, Oracle, MSSQL, Db2 and
+  friends. SQLite and MySQL have no sequences and report that explicitly rather
+  than emitting SQL the driver rejects
 - **Table Partitions**: RANGE, LIST, HASH partitioning (across supported dialects)
 - **Partial Indexes**: Conditional indexes for MySQL, MariaDB, PostgreSQL, Oracle, MSSQL
 - **Row-Level Security (RLS)**: PostgreSQL, Oracle VPD, MSSQL Security Policies
 - **Materialized Views**: With FAST/COMPLETE refresh (PostgreSQL, Oracle)
 - **Views**: Database views support
-- **Full-Text Search**: SQLite FTS5 and PostgreSQL full-text search
+- **Full-Text Search**: one `createFullTextIndex()` call resolves per dialect —
+  GIN over `to_tsvector` on PostgreSQL, `FULLTEXT` on MySQL/MariaDB, FTS5 on SQLite
 - **JSON/JSONB**: Native JSON data type support
 - **Spatial Data**: PostGIS support for PostgreSQL
 - **Foreign Data Wrappers**: PostgreSQL FDW support
@@ -36,6 +48,10 @@ A TypeScript ORM supporting multiple database dialects with full TypeScript supp
 - **Audit Logging**: Built-in audit trail functionality
 - **Polymorphic Associations**: Built-in helpers for polymorphic relationships
 - **Self-referential Associations**: Tree structure support
+- **Object, key-value and document stores**: S3, MinIO, R2, GCS, Azure Blob, Redis,
+  MongoDB, DynamoDB, Cassandra, Elasticsearch and ~90 more ship as standalone
+  `*Store` classes with APIs matching each engine. These are **not** part of the
+  model/relation layer — see [NoSQL Stores](#nosql-stores)
 
 ## Installation
 
@@ -100,6 +116,19 @@ SQL dialects and 102 NoSQL/data stores (129 engines). Full taxonomy:
 
 ## Supported Dialects
 
+**How these are verified.** SQLite and DuckDB are embedded, so the test suite runs
+against the real engine on every commit. PostgreSQL, MySQL, MariaDB, MSSQL, Oracle,
+CockroachDB and ClickHouse have real servers available via `docker-compose.test.yml`
+and are exercised by `npm run test:integration`. The remaining dialects are covered
+by unit tests against an in-memory SQL simulator, which checks generated SQL but not
+engine behaviour. "Stable" below means the implementation is complete, not that it
+has been run against that vendor's server in CI.
+
+Dialects not listed in the table are implemented as subclasses of a core dialect and
+inherit its behaviour: TimescaleDB, Greenplum, YugabyteDB, Vertica, Trino, Exasol,
+CrateDB, QuestDB and Firebird extend PostgreSQL; TiDB, SingleStore and Databricks
+extend MySQL; Turso/libSQL extends SQLite.
+
 | Dialect | Status | Features |
 |---------|--------|-----------|
 | SQLite | Stable | FTS5, CTEs, Window Functions, UPSERT |
@@ -152,7 +181,7 @@ index map, flowchart, tree, Chen-ER, package, gantt) built on a shared
 DOM-backed SVG builder with light/dark themes and configurable accent colours.
 
 ```ts
-import { ModelDiagram } from '@mstone6969/prorm';
+import { ModelDiagram } from 'ts-prorm-orm';
 
 new ModelDiagram({
   name: 'User',
@@ -164,6 +193,74 @@ new ModelDiagram({
 
 See the [diagram module guide](./docs/diagrams/README.md) for every generator.
 
+## External Fields
+
+A model field whose *contents* live in an object or key-value store, while the
+row lives in the database. The table column holds only the object key; the ORM
+keeps the two in step, so the link between a row and its object isn't something
+you maintain by hand.
+
+```typescript
+import { Prorm, DataTypes, ExternalField, Table, Column, PrimaryKey, AutoIncrement } from 'ts-prorm-orm';
+import { S3Store } from 'ts-prorm-orm';
+
+const s3 = new S3Store({ region: 'us-east-1' });
+await s3.connect();
+
+prorm.registerStore('assets', s3, { defaultBucket: 'avatars' });
+
+@Table()
+class User {
+  @Column(DataTypes.INTEGER())
+  @PrimaryKey()
+  @AutoIncrement()
+  declare id: number;
+
+  @Column(DataTypes.STRING(100))
+  declare name: string;
+
+  // `avatarKey` is registered for you; only the key is stored in the table
+  @ExternalField({ store: 'assets', contentType: 'image/png' })
+  declare avatar: Buffer;
+}
+
+prorm.addModel(User);
+await prorm.sync();
+
+const user = await User.create({ name: 'Ada' });
+
+user.avatar = pngBytes;
+await user.save();          // PUT to S3, then persists avatarKey
+
+const fetched = await User.findByPk(user.id);
+await fetched.loadAvatar(); // GET from S3
+fetched.avatar;             // Buffer
+
+await fetched.deleteAvatar(); // removes the object and clears the key
+await fetched.destroy();      // deleting the row cleans up its objects
+```
+
+Each external field `x` gets `loadX()`, `saveX(value)`, `deleteX()` and `hasX()`.
+
+**Any shipped store works without an adapter.** S3, MinIO, R2, GCS, Azure Blob
+and Redis all have different method names (`putObject` vs `uploadObject` vs
+`uploadBlob`; `deleteObject` vs `removeObject` vs `deleteBlob`) — these are
+normalized internally, so `registerStore()` takes the store directly. Key-value
+stores have no bucket concept, so a configured bucket becomes a key prefix, and
+binary payloads round-trip through base64.
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `store` | — | Name the store was registered under |
+| `bucket` | store's `defaultBucket` | Bucket/container; a key prefix on key-value stores |
+| `keyColumn` | `<field>Key` | Column holding the object key |
+| `keyPrefix` | `<field>/` | Prefix for generated keys |
+| `contentType` | — | Recorded on write where the store supports it |
+| `encoding` | `buffer` | `buffer`, `utf8`, or `json` (parsed on read, stringified on write) |
+
+Pass your own object implementing `ExternalStoreAdapter` to `registerStore()` for
+a store that isn't recognized.
+
 ## NoSQL Stores
 
 NoSQL engines don't share the SQL-shaped `Dialect` interface used above (no `query(sql)`, no identifier escaping, no DDL). Instead, each is its own store class under `src/nosql/<name>/`, exposing the operations that engine actually supports — see each store's README for full details.
@@ -175,7 +272,7 @@ NoSQL engines don't share the SQL-shaped `Dialect` interface used above (no `que
 | Amazon DynamoDB | Stable | `@aws-sdk/client-dynamodb` + `@aws-sdk/lib-dynamodb`, partition/sort-key CRUD, Query/Scan, batch and transactional writes, no arbitrary queries |
 
 ```ts
-import { MongoStore, RedisStore, DynamoDbStore } from '@mstone6969/prorm';
+import { MongoStore, RedisStore, DynamoDbStore } from 'ts-prorm-orm';
 
 const mongo = new MongoStore({ uri: 'mongodb://localhost:27017', database: 'app' });
 await mongo.connect();
@@ -214,7 +311,7 @@ unit-tested without the driver installed. Full pages under
 | [RethinkDBStore](./docs/stores/rethinkdb.md) | `rethinkdb-ts` | RethinkDB |
 
 ```ts
-import { S3Store, KafkaStore } from '@mstone6969/prorm';
+import { S3Store, KafkaStore } from 'ts-prorm-orm';
 
 const s3 = new S3Store({ region: 'us-east-1' });
 await s3.connect();
@@ -255,12 +352,13 @@ const User = prorm.define('User', {
   }
 });
 
-// Use FTS5 for full-text search
-await prorm.query(`
-  CREATE VIRTUAL TABLE IF NOT EXISTS users_fts USING fts5(
-    name, email, content='users', content_rowid='id'
-  )
-`);
+// Full-text search (FTS5 on SQLite, GIN/to_tsvector on Postgres,
+// FULLTEXT on MySQL/MariaDB - the dialect decides)
+await prorm.getQueryInterface().createFullTextIndex({
+  name: 'users_fts',
+  table: 'users',
+  columns: ['name', 'email'],
+});
 
 // Upsert (INSERT OR REPLACE)
 await User.upsert({
@@ -304,18 +402,25 @@ const User = prorm.define('User', {
   }
 });
 
-// Create stored procedure
-await prorm.query(`
-  CREATE PROCEDURE get_user_by_email(IN user_email VARCHAR(255))
-  BEGIN
-    SELECT * FROM users WHERE email = user_email;
-  END
-`);
-
-// Call stored procedure
-await prorm.query('CALL get_user_by_email(?)', {
-  replacements: ['john@example.com']
-});
+// Declare a stored procedure with @Procedure, then let sync() create it
+import { Procedure, ProcedureRegistry } from 'ts-prorm-orm';
+
+class UserProcedures {
+  @Procedure({
+    name: 'get_user_by_email',
+    params: [{ name: 'user_email', type: 'VARCHAR(255)', mode: 'IN' }],
+    body: 'SELECT * FROM users WHERE email = user_email;',
+  })
+  getUserByEmail(email: string) {}
+}
+
+prorm.registerProcedures(UserProcedures);
+await prorm.sync(); // issues the CREATE PROCEDURE
+
+// Call it
+const rows = await ProcedureRegistry.call(
+  prorm, UserProcedures, 'getUserByEmail', ['john@example.com']
+);
 ```
 
 ### PostgreSQL
@@ -356,26 +461,26 @@ const User = prorm.define('User', {
   properties: DataTypes.HSTORE,
 });
 
-// Row-Level Security (RLS)
-await prorm.query(`
-  ALTER TABLE users ENABLE ROW LEVEL SECURITY
-`);
+const qi = prorm.getQueryInterface();
 
-await prorm.query(`
-  CREATE POLICY users_policy ON users
-  USING (user_id = current_user_id())
-`);
+// Row-Level Security (RLS)
+await qi.enableRowLevelSecurity('users');
+await qi.createPolicy({
+  name: 'users_policy',
+  table: 'users',
+  using: 'user_id = current_user_id()',
+});
 
 // Full-text search
-await prorm.query(`
-  CREATE INDEX users_fts_idx ON users
-  USING GIN (to_tsvector('english', name || ' ' || email))
-`);
+await qi.createFullTextIndex({
+  name: 'users_fts_idx',
+  table: 'users',
+  columns: ['name', 'email'],
+  language: 'english',
+});
 
-// Sequence example
-await prorm.query(`
-  CREATE SEQUENCE user_id_seq START WITH 1000
-`);
+// Sequence
+await qi.createSequence('user_id_seq', { start: 1000 });
 ```
 
 ### MariaDB
@@ -411,17 +516,22 @@ const Product = prorm.define('Product', {
   attributes: DataTypes.JSON,
 });
 
-// Stored procedure
-await prorm.query(`
-  CREATE PROCEDURE get_products_by_price(IN min_price DECIMAL(10,2))
-  BEGIN
-    SELECT * FROM products WHERE price >= min_price;
-  END
-`);
+// Stored procedure - declared once, created by sync()
+class ProductProcedures {
+  @Procedure({
+    name: 'get_products_by_price',
+    params: [{ name: 'min_price', type: 'DECIMAL(10,2)', mode: 'IN' }],
+    body: 'SELECT * FROM products WHERE price >= min_price;',
+  })
+  getProductsByPrice(minPrice: number) {}
+}
+
+prorm.registerProcedures(ProductProcedures);
+await prorm.sync();
 
-await prorm.query('CALL get_products_by_price(?)', {
-  replacements: [10.00]
-});
+const rows = await ProcedureRegistry.call(
+  prorm, ProductProcedures, 'getProductsByPrice', [10.0]
+);
 ```
 
 ### Oracle
@@ -453,19 +563,23 @@ const Employee = prorm.define('Employee', {
 });
 
 // Oracle sequence
-await prorm.query(`
-  CREATE SEQUENCE employee_seq START WITH 1000 INCREMENT BY 1
-`);
+await prorm.getQueryInterface().createSequence('employee_seq', {
+  start: 1000,
+  increment: 1,
+});
 
-// Stored procedure with OUT parameter
-await prorm.query(`
-  CREATE OR REPLACE PROCEDURE get_employee_count(
-    p_count OUT NUMBER
-  ) AS
-  BEGIN
-    SELECT COUNT(*) INTO p_count FROM employees;
-  END;
-`);
+// Stored procedure with an OUT parameter
+class EmployeeProcedures {
+  @Procedure({
+    name: 'get_employee_count',
+    params: [{ name: 'p_count', type: 'NUMBER', mode: 'OUT' }],
+    body: 'SELECT COUNT(*) INTO p_count FROM employees;',
+  })
+  getEmployeeCount() {}
+}
+
+prorm.registerProcedures(EmployeeProcedures);
+await prorm.sync();
 ```
 
 ### MSSQL
@@ -499,11 +613,14 @@ const Order = prorm.define('Order', {
 });
 
 // MSSQL sequence
-await prorm.query(`
-  CREATE SEQUENCE order_id_seq START WITH 1000 INCREMENT BY 1
-`);
+await prorm.getQueryInterface().createSequence('order_id_seq', {
+  start: 1000,
+  increment: 1,
+});
 
-// Row-Level Security
+// Row-Level Security. SQL Server models RLS as a security policy bound to a
+// predicate function rather than as a per-table policy, and prorm has no
+// builder for it yet - this is one of the few places raw SQL is still needed.
 await prorm.query(`
   CREATE SECURITY POLICY SalesFilter
   ADD FILTER PREDICATE dbo.fn_tenantAccessPredicate(TenantId)
@@ -515,7 +632,7 @@ await prorm.query(`
 
 ```bash
 # Generate a model
-npm run model:generate -- --name User --attributes name:string,email:string
+npm run model:create -- --name User --attributes name:string,email:string
 
 # Run migrations
 npm run model:create
@@ -568,6 +685,11 @@ In-depth, code-level reference docs for each major subsystem, living alongside t
 
 Online documentation: [GitLab Pages](https://malcolmston.gitlab.io/prod-orm)
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow, testing,
+the release/publish flow, and the CI/CD + deployment runbook.
+
 ## License
 
 MIT

package/dist/audit/history-query.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Audit History Query methods
+ * Provides model-level and instance-level methods for querying audit history
+ */
+import { AuditLogger } from './logger';
+/**
+ * Set the global AuditLogger instance
+ * This should be called once when setting up audit logging
+ *
+ * @param logger - The AuditLogger instance
+ */
+export declare function setAuditLogger(logger: AuditLogger): void;
+/**
+ * Get the current AuditLogger instance
+ */
+export declare function getAuditLogger(): AuditLogger | null;
+/**
+ * Add model-level audit history methods to a Model class
+ *
+ * @param model - The Model static (class) to add methods to
+ */
+export declare function addAuditHistoryToModel(model: any): void;
+/**
+ * Add instance-level audit history methods to a ModelInstance
+ *
+ * @param instance - The Model instance prototype
+ */
+export declare function addAuditHistoryToInstance(instance: any): void;
+declare const _default: {
+    setAuditLogger: typeof setAuditLogger;
+    getAuditLogger: typeof getAuditLogger;
+    addAuditHistoryToModel: typeof addAuditHistoryToModel;
+    addAuditHistoryToInstance: typeof addAuditHistoryToInstance;
+};
+export default _default;

package/dist/audit/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Audit Module
+ * Provides audit logging capabilities for tracking model changes
+ */
+export { AuditLogger, AuditLog, AuditLoggerOptions } from './logger';
+export { setAuditLogger, getAuditLogger, addAuditHistoryToModel, addAuditHistoryToInstance, } from './history-query';
+import { AuditLogger } from './logger';
+import { setAuditLogger, getAuditLogger, addAuditHistoryToModel, addAuditHistoryToInstance } from './history-query';
+declare const _default: {
+    AuditLogger: typeof AuditLogger;
+    setAuditLogger: typeof setAuditLogger;
+    getAuditLogger: typeof getAuditLogger;
+    addAuditHistoryToModel: typeof addAuditHistoryToModel;
+    addAuditHistoryToInstance: typeof addAuditHistoryToInstance;
+};
+export default _default;

package/dist/audit/logger.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Audit Logger for the TypeScript ORM
+ * Provides persistent audit logging for model changes with database storage
+ */
+import { Prorm, ModelStatic } from '../prorm';
+/**
+ * Represents a single audit log entry
+ */
+export interface AuditLog {
+    /** Unique identifier for the audit log entry */
+    id: number;
+    /** Name of the table that was modified */
+    tableName: string;
+    /** Type of action performed (CREATE, UPDATE, DELETE) */
+    action: 'CREATE' | 'UPDATE' | 'DELETE';
+    /** Primary key identifier of the affected record */
+    recordId: string | number;
+    /** Previous state of the record (for UPDATE/DELETE) */
+    oldValues?: Record<string, any>;
+    /** New state of the record (for CREATE/UPDATE) */
+    newValues?: Record<string, any>;
+    /** ID of the user who made the change */
+    userId?: string | number;
+    /** Timestamp of when the change occurred */
+    timestamp: Date;
+    /** IP address of the client that made the change */
+    ipAddress?: string;
+}
+/**
+ * Options for configuring the AuditLogger
+ */
+export interface AuditLoggerOptions {
+    /** Custom table name for the audit log. Default: 'AuditLogs' */
+    tableName?: string;
+    /** Function to get the current user ID */
+    userIdGetter?: () => string | number | undefined;
+    /** Function to get the current IP address */
+    ipAddressGetter?: () => string | undefined;
+    /** Custom model name for the audit log model */
+    modelName?: string;
+}
+/**
+ * AuditLogger - Provides persistent audit logging for model changes
+ *
+ * @example
+ * const auditLogger = new AuditLogger(prorm);
+ * await auditLogger.setupHooks();
+ *
+ * // Manually log an action
+ * await auditLogger.logAction('CREATE', 'User', 1, {}, { name: 'John' });
+ *
+ * // Get audit history
+ * const history = await auditLogger.getHistory('User', 1);
+ */
+export declare class AuditLogger {
+    private prorm;
+    private options;
+    private auditModel;
+    private hookedModels;
+    /**
+     * Create a new AuditLogger instance
+     *
+     * @param prorm - The Prorm instance
+     * @param options - Optional configuration options
+     */
+    constructor(prorm: Prorm, options?: AuditLoggerOptions);
+    /**
+     * Get the audit model
+     */
+    getModel(): ModelStatic<any> | null;
+    /**
+     * Get the current user ID
+     */
+    private getUserId;
+    /**
+     * Get the current IP address
+     */
+    private getIpAddress;
+    /**
+     * Define and create the audit log model
+     */
+    private ensureAuditModel;
+    /**
+     * Log an audit action
+     *
+     * @param action - The type of action (CREATE, UPDATE, DELETE)
+     * @param tableName - The name of the table
+     * @param recordId - The primary key of the record
+     * @param oldValues - The previous values (for UPDATE/DELETE)
+     * @param newValues - The new values (for CREATE/UPDATE)
+     */
+    logAction(action: 'CREATE' | 'UPDATE' | 'DELETE', tableName: string, recordId: string | number, oldValues?: Record<string, any>, newValues?: Record<string, any>): Promise<void>;
+    /**
+     * Get audit history for a table and optional record
+     *
+     * @param tableName - The name of the table
+     * @param recordId - Optional record ID to filter by
+     * @param options - Query options
+     */
+    getHistory(tableName: string, recordId?: string | number, options?: {
+        limit?: number;
+        offset?: number;
+        startDate?: Date;
+        endDate?: Date;
+    }): Promise<AuditLog[]>;
+    /**
+     * Setup hooks for all models to automatically log changes
+     *
+     * This method iterates through all registered models and adds
+     * beforeCreate, beforeUpdate, and beforeDestroy hooks
+     */
+    setupHooks(): void;
+    /**
+     * Add audit hooks to a specific model
+     *
+     * @param model - The model to add hooks to
+     */
+    addHooksToModel(model: ModelStatic<any>): void;
+    /**
+     * Check if a model has audit hooks
+     *
+     * @param model - The model to check
+     */
+    hasHooks(model: ModelStatic<any>): boolean;
+}
+export default AuditLogger;