dyna-record 0.0.1

package/README.md

@@ -0,0 +1,3 @@
+# dyna-record
+
+Typescript Object Relational Mapper (ORM) for Dynamo

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./src";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src"), exports);

package/dist/src/DynaRecord.d.ts

@@ -0,0 +1,216 @@
+import { type QueryOptions as QueryBuilderOptions } from "./query-utils";
+import { type FindByIdOptions, type FindByIdIncludesRes, type QueryOptions, type EntityKeyConditions, type QueryResults, type CreateOptions, type UpdateOptions } from "./operations";
+import type { EntityClass, Optional } from "./types";
+interface DynaRecordBase {
+    id: string;
+    type: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Serves as an abstract base class for entities in the ORM system. It defines standard fields such as `id`, `type`, `createdAt`, and `updatedAt`, and provides static methods for CRUD operations and queries. This class encapsulates common behaviors and properties that all entities share, leveraging decorators for attribute metadata and supporting operations like finding, creating, updating, and deleting entities.
+ *
+ * Table classes should extend this class, and each entity should extend the table class
+ *
+ * Entities extending `DynaRecord` can utilize these operations to interact with their corresponding records in the database, including handling relationships between different entities.
+ * @example
+ * ```typescript
+ * @Table({ name: "my-table", delimiter: "#" })
+ * abstract class MyTable extends DynaRecord {
+ *   @PartitionKeyAttribute()
+ *   public readonly pk: PartitionKey;
+ *
+ *   @SortKeyAttribute()
+ *   public readonly sk: SortKey;
+ * }
+ *
+ * @Entity
+ * class User extends MyTable {
+ *  // User implementation
+ * }
+ * ```
+ */
+declare abstract class DynaRecord implements DynaRecordBase {
+    /**
+     * A unique identifier for the entity itself, automatically generated upon creation.
+     */
+    readonly id: string;
+    /**
+     * The type of the Entity
+     */
+    readonly type: string;
+    /**
+     * The timestamp marking when the entity was created
+     */
+    readonly createdAt: Date;
+    /**
+     * The timestamp marking the last update to the entity. Initially set to the same value as `createdAt`.
+     */
+    readonly updatedAt: Date;
+    /**
+     * Find an entity by Id and optionally include associations
+     * @param {string} id - Entity Id
+     * @param {Object} options - FindByIdOptions
+     * @returns An entity with included associations serialized
+     *
+     * @example Without included relationships
+     * ```typescript
+     * const user = await User.findById("userId");
+     * ```
+     *
+     * @example With included relationships
+     * ```typescript
+     * const user = await User.findById("userId", { include: [{ association: "profile" }] });
+     * ```
+     */
+    static findById<T extends DynaRecord, Opts extends FindByIdOptions<T>>(this: EntityClass<T>, id: string, options?: Opts): Promise<Optional<T | FindByIdIncludesRes<T, Opts>>>;
+    /**
+     * Query by PartitionKey and optional SortKey/Filter/Index conditions
+     * @param {Object} key - PartitionKey value and optional SortKey condition. Keys must be attributes defined on the model
+     * @param {Object=} options - QueryBuilderOptions
+     *
+     * @example By partition key only
+     * ```typescript
+     * const user = await User.query({ pk: "User#123" });
+     * ```
+     *
+     * @example By partition key and sort key exact match
+     * ```typescript
+     * const user = await User.query({ pk: "User#123", sk: "Profile#123" });
+     * ```
+     *
+     * @example By partition key and sort key begins with
+     * ```typescript
+     * const user = await User.query({ pk: "User#123", sk: { $beginsWith: "Profile" } });
+     * ```
+     *
+     * @example With filter (arbitrary example)
+     * ```typescript
+     * const result = await User.query(
+     *  {
+     *    myPk: "User|123"
+     *  },
+     *  {
+     *    filter: {
+     *    type: ["BelongsToLink", "Profile"],
+     *    createdAt: { $beginsWith: "202" },
+     *    $or: [
+     *      {
+     *        foreignKey: "111",
+     *        updatedAt: { $beginsWith: "2023-02-15" }
+     *      },
+     *      {
+     *        foreignKey: ["222", "333"],
+     *        createdAt: { $beginsWith: "2021-09-15T" },
+     *        foreignEntityType: "Order"
+     *      },
+     *      {
+     *        id: "123"
+     *      }
+     *    ]
+     *  }
+     * }
+     *);
+     * ```
+     *
+     * @example On index
+     * ```typescript
+     *  const result = await User.query(
+     *    {
+     *      pk: "User#123",
+     *      sk: { $beginsWith: "Profile" }
+     *    },
+     *    { indexName: "myIndex" }
+     *  );
+     * ```
+     */
+    static query<T extends DynaRecord>(this: EntityClass<T>, key: EntityKeyConditions<T>, options?: QueryBuilderOptions): Promise<QueryResults<T>>;
+    /**
+     * Query an EntityPartition by EntityId and optional SortKey/Filter conditions.
+     * QueryByIndex not supported. Use Query with keys if indexName is needed
+     * @param {string} id - Entity Id
+     * @param {Object=} options - QueryOptions. Supports filter and skCondition. indexName is not supported
+     *
+     * @example By partition key only
+     * ```typescript
+     * const user = await User.query("123");
+     * ```
+     *
+     * @example By partition key and sort key exact match
+     * ```typescript
+     * const user = await User.query("123", { skCondition: "Profile#111" });
+     * ```
+     *
+     * @example By partition key and sort key begins with
+     * ```typescript
+     * const user = await User.query("123", { skCondition: { $beginsWith: "Profile" } })
+     * ```
+     *
+     * @example With filter (arbitrary example)
+     * ```typescript
+     * const user = await User.query("123", {
+     *   filter: {
+     *     type: "BelongsToLink",
+     *     createdAt: "2023-11-21T12:31:21.148Z"
+     *    }
+     * });
+     * ```
+     */
+    static query<T extends DynaRecord>(this: EntityClass<T>, id: string, options?: Omit<QueryOptions, "indexName">): Promise<QueryResults<T>>;
+    /**
+     * Create an entity. If foreign keys are included in the attributes then BelongsToLinks will be demoralized accordingly
+     * @param attributes - Attributes of the model to create
+     * @returns The new Entity
+     *
+     * ```typescript
+     * const newUser = await User.create({ name: "Alice", email: "alice@example.com", profileId: "123" });
+     * ```
+     */
+    static create<T extends DynaRecord>(this: EntityClass<T>, attributes: CreateOptions<T>): Promise<T>;
+    /**
+     * Update an entity. If foreign keys are included in the attribute then:
+     *   - BelongsToLinks will be created accordingly
+     *   - If the entity already had a foreign key relationship, then those BelongsToLinks will be deleted
+     *     - If the foreign key is not nullable then a {@link NullConstraintViolationError} is thrown. See {@link NullableForeignKeyAttribute}
+     *   - Validation errors will be thrown if the attribute being removed is not nullable
+     * @param id - The id of the entity to update
+     * @param attributes - Attributes to update
+     *
+     *
+     * @example Updating an entity.
+     * ```typescript
+     * await User.update("userId", { email: "newemail@example.com", profileId: 789 });
+     * ```
+     *
+     * @example Removing a nullable entities attributes
+     * ```typescript
+     * await User.update("userId", { email: "newemail@example.com", someKey: null });
+     * ```
+     */
+    static update<T extends DynaRecord>(this: EntityClass<T>, id: string, attributes: UpdateOptions<T>): Promise<void>;
+    /**
+     * Delete an entity by ID
+     *   - Delete all BelongsToLinks
+     *   - Disassociate all foreign keys of linked models
+     * @param id - The id of the entity to update
+     *
+     * @example Delete an entity
+     * ```typescript
+     * await User.delete("userId");
+     * ```
+     */
+    static delete<T extends DynaRecord>(this: EntityClass<T>, id: string): Promise<void>;
+    /**
+     * Constructs the partition key value
+     * @param {string} id - Entity Id
+     * @returns Constructed partition key value
+     *
+     * @example
+     * ```typescript
+     * const pkValue = User.partitionKeyValue("userId");
+     * ```
+     */
+    static partitionKeyValue(id: string): string;
+}
+export default DynaRecord;
+//# sourceMappingURL=DynaRecord.d.ts.map

package/dist/src/DynaRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynaRecord.d.ts","sourceRoot":"","sources":["../../src/DynaRecord.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,YAAY,IAAI,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAExB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAEjB,KAAK,aAAa,EAElB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAErD,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uBAAe,UAAW,YAAW,cAAc;IACjD;;OAEG;IACH,SACgB,EAAE,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,SACgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SACgB,SAAS,EAAE,IAAI,CAAC;IAEhC;;OAEG;IACH,SACgB,SAAS,EAAE,IAAI,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;WACiB,QAAQ,CAC1B,CAAC,SAAS,UAAU,EACpB,IAAI,SAAS,eAAe,CAAC,CAAC,CAAC,EAE/B,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,IAAI,GACb,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAKtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;WACiB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC5C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,GAAG,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;WACiB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC5C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GACxC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAW3B;;;;;;;;OAQG;WACiB,MAAM,CAAC,CAAC,SAAS,UAAU,EAC7C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC;IAKb;;;;;;;;;;;;;;;;;;;OAmBG;WACiB,MAAM,CAAC,CAAC,SAAS,UAAU,EAC7C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;;;OAUG;WACiB,MAAM,CAAC,CAAC,SAAS,UAAU,EAC7C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;;OASG;WACW,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;CAIpD;AAED,eAAe,UAAU,CAAC"}

package/dist/src/DynaRecord.js

@@ -0,0 +1,217 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = __importStar(require("./metadata"));
+const decorators_1 = require("./decorators");
+const operations_1 = require("./operations");
+/**
+ * Serves as an abstract base class for entities in the ORM system. It defines standard fields such as `id`, `type`, `createdAt`, and `updatedAt`, and provides static methods for CRUD operations and queries. This class encapsulates common behaviors and properties that all entities share, leveraging decorators for attribute metadata and supporting operations like finding, creating, updating, and deleting entities.
+ *
+ * Table classes should extend this class, and each entity should extend the table class
+ *
+ * Entities extending `DynaRecord` can utilize these operations to interact with their corresponding records in the database, including handling relationships between different entities.
+ * @example
+ * ```typescript
+ * @Table({ name: "my-table", delimiter: "#" })
+ * abstract class MyTable extends DynaRecord {
+ *   @PartitionKeyAttribute()
+ *   public readonly pk: PartitionKey;
+ *
+ *   @SortKeyAttribute()
+ *   public readonly sk: SortKey;
+ * }
+ *
+ * @Entity
+ * class User extends MyTable {
+ *  // User implementation
+ * }
+ * ```
+ */
+let DynaRecord = (() => {
+    let _instanceExtraInitializers = [];
+    let _id_decorators;
+    let _id_initializers = [];
+    let _type_decorators;
+    let _type_initializers = [];
+    let _createdAt_decorators;
+    let _createdAt_initializers = [];
+    let _updatedAt_decorators;
+    let _updatedAt_initializers = [];
+    return class DynaRecord {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _id_decorators = [(0, decorators_1.Attribute)({ alias: metadata_1.tableDefaultFields.id.alias })];
+            _type_decorators = [(0, decorators_1.Attribute)({ alias: metadata_1.tableDefaultFields.type.alias })];
+            _createdAt_decorators = [(0, decorators_1.DateAttribute)({ alias: metadata_1.tableDefaultFields.createdAt.alias })];
+            _updatedAt_decorators = [(0, decorators_1.DateAttribute)({ alias: metadata_1.tableDefaultFields.updatedAt.alias })];
+            __esDecorate(null, null, _id_decorators, { kind: "field", name: "id", static: false, private: false, access: { has: obj => "id" in obj, get: obj => obj.id, set: (obj, value) => { obj.id = value; } }, metadata: _metadata }, _id_initializers, _instanceExtraInitializers);
+            __esDecorate(null, null, _type_decorators, { kind: "field", name: "type", static: false, private: false, access: { has: obj => "type" in obj, get: obj => obj.type, set: (obj, value) => { obj.type = value; } }, metadata: _metadata }, _type_initializers, _instanceExtraInitializers);
+            __esDecorate(null, null, _createdAt_decorators, { kind: "field", name: "createdAt", static: false, private: false, access: { has: obj => "createdAt" in obj, get: obj => obj.createdAt, set: (obj, value) => { obj.createdAt = value; } }, metadata: _metadata }, _createdAt_initializers, _instanceExtraInitializers);
+            __esDecorate(null, null, _updatedAt_decorators, { kind: "field", name: "updatedAt", static: false, private: false, access: { has: obj => "updatedAt" in obj, get: obj => obj.updatedAt, set: (obj, value) => { obj.updatedAt = value; } }, metadata: _metadata }, _updatedAt_initializers, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        /**
+         * A unique identifier for the entity itself, automatically generated upon creation.
+         */
+        id = (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _id_initializers, void 0));
+        /**
+         * The type of the Entity
+         */
+        type = __runInitializers(this, _type_initializers, void 0);
+        /**
+         * The timestamp marking when the entity was created
+         */
+        createdAt = __runInitializers(this, _createdAt_initializers, void 0);
+        /**
+         * The timestamp marking the last update to the entity. Initially set to the same value as `createdAt`.
+         */
+        updatedAt = __runInitializers(this, _updatedAt_initializers, void 0);
+        /**
+         * Find an entity by Id and optionally include associations
+         * @param {string} id - Entity Id
+         * @param {Object} options - FindByIdOptions
+         * @returns An entity with included associations serialized
+         *
+         * @example Without included relationships
+         * ```typescript
+         * const user = await User.findById("userId");
+         * ```
+         *
+         * @example With included relationships
+         * ```typescript
+         * const user = await User.findById("userId", { include: [{ association: "profile" }] });
+         * ```
+         */
+        static async findById(id, options) {
+            const op = new operations_1.FindById(this);
+            return await op.run(id, options);
+        }
+        static async query(key, options) {
+            const op = new operations_1.Query(this);
+            return await op.run(key, options);
+        }
+        /**
+         * Create an entity. If foreign keys are included in the attributes then BelongsToLinks will be demoralized accordingly
+         * @param attributes - Attributes of the model to create
+         * @returns The new Entity
+         *
+         * ```typescript
+         * const newUser = await User.create({ name: "Alice", email: "alice@example.com", profileId: "123" });
+         * ```
+         */
+        static async create(attributes) {
+            const op = new operations_1.Create(this);
+            return await op.run(attributes);
+        }
+        /**
+         * Update an entity. If foreign keys are included in the attribute then:
+         *   - BelongsToLinks will be created accordingly
+         *   - If the entity already had a foreign key relationship, then those BelongsToLinks will be deleted
+         *     - If the foreign key is not nullable then a {@link NullConstraintViolationError} is thrown. See {@link NullableForeignKeyAttribute}
+         *   - Validation errors will be thrown if the attribute being removed is not nullable
+         * @param id - The id of the entity to update
+         * @param attributes - Attributes to update
+         *
+         *
+         * @example Updating an entity.
+         * ```typescript
+         * await User.update("userId", { email: "newemail@example.com", profileId: 789 });
+         * ```
+         *
+         * @example Removing a nullable entities attributes
+         * ```typescript
+         * await User.update("userId", { email: "newemail@example.com", someKey: null });
+         * ```
+         */
+        static async update(id, attributes) {
+            const op = new operations_1.Update(this);
+            await op.run(id, attributes);
+        }
+        /**
+         * Delete an entity by ID
+         *   - Delete all BelongsToLinks
+         *   - Disassociate all foreign keys of linked models
+         * @param id - The id of the entity to update
+         *
+         * @example Delete an entity
+         * ```typescript
+         * await User.delete("userId");
+         * ```
+         */
+        static async delete(id) {
+            const op = new operations_1.Delete(this);
+            await op.run(id);
+        }
+        /**
+         * Constructs the partition key value
+         * @param {string} id - Entity Id
+         * @returns Constructed partition key value
+         *
+         * @example
+         * ```typescript
+         * const pkValue = User.partitionKeyValue("userId");
+         * ```
+         */
+        static partitionKeyValue(id) {
+            const { delimiter } = metadata_1.default.getEntityTable(this.name);
+            return `${this.name}${delimiter}${id}`;
+        }
+    };
+})();
+exports.default = DynaRecord;

package/dist/src/Logger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Facilitates logging throughout the ORM system with support for different log levels: log, warn, error, and info. Logging can be toggled through the `DYNA_RECORD_LOGGING_ENABLED` environment variable. When enabled, logs are output to the console, allowing for easy tracking and debugging of the system's operations.
+ *
+ * The Logger class abstracts the console's logging methods, providing a unified API for logging across different severity levels. This encapsulation allows for more flexible logging strategies and makes it easier to modify logging behavior centrally.
+ *
+ * Each logging method accepts parameters matching those of the corresponding console method, ensuring that the Logger can be used in the same way as direct console logging while adding the capability to control logging behavior through environment variables.
+ *
+ * @method log - Outputs general informational messages to the console. Intended for logging detailed information about the flow of the application.
+ * @method warn - Outputs warnings to the console. Used for situations that aren't errors but could potentially lead to errors or undesired behavior.
+ * @method error - Outputs error messages to the console. Used for logging errors and exceptions that occur during the application's execution.
+ * @method info - Outputs informational messages to the console, similar to `log`. Can be used to log high-level information about the application's state or operations.
+ */
+declare class Logger {
+    /**
+     * If debug logging is enabled, it will log to console at the given log level
+     * @param level
+     * @param logParams
+     */
+    private static _log;
+    /**
+     * Logs general informational messages.
+     * @param messages
+     */
+    static log(...messages: Parameters<Console["log"]>): void;
+    /**
+     * Logs warning messages.
+     * @param messages
+     */
+    static warn(...messages: Parameters<Console["warn"]>): void;
+    /**
+     * Logs error messages.
+     * @param messages
+     */
+    static error(...messages: Parameters<Console["error"]>): void;
+    /**
+     * Logs info messages.
+     * @param messages
+     */
+    static info(...messages: Parameters<Console["info"]>): void;
+}
+export default Logger;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/src/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,cAAM,MAAM;IACV;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,IAAI;IAMnB;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;IAIzD;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAI3D;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI;IAI7D;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;CAG5D;AAED,eAAe,MAAM,CAAC"}

package/dist/src/Logger.js

@@ -0,0 +1,57 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Facilitates logging throughout the ORM system with support for different log levels: log, warn, error, and info. Logging can be toggled through the `DYNA_RECORD_LOGGING_ENABLED` environment variable. When enabled, logs are output to the console, allowing for easy tracking and debugging of the system's operations.
+ *
+ * The Logger class abstracts the console's logging methods, providing a unified API for logging across different severity levels. This encapsulation allows for more flexible logging strategies and makes it easier to modify logging behavior centrally.
+ *
+ * Each logging method accepts parameters matching those of the corresponding console method, ensuring that the Logger can be used in the same way as direct console logging while adding the capability to control logging behavior through environment variables.
+ *
+ * @method log - Outputs general informational messages to the console. Intended for logging detailed information about the flow of the application.
+ * @method warn - Outputs warnings to the console. Used for situations that aren't errors but could potentially lead to errors or undesired behavior.
+ * @method error - Outputs error messages to the console. Used for logging errors and exceptions that occur during the application's execution.
+ * @method info - Outputs informational messages to the console, similar to `log`. Can be used to log high-level information about the application's state or operations.
+ */
+class Logger {
+    /**
+     * If debug logging is enabled, it will log to console at the given log level
+     * @param level
+     * @param logParams
+     */
+    static _log(level, ...logParams) {
+        if (process.env.DYNA_RECORD_LOGGING_ENABLED === "true") {
+            console[level](...logParams);
+        }
+    }
+    /**
+     * Logs general informational messages.
+     * @param messages
+     */
+    static log(...messages) {
+        this._log("log", ...messages);
+    }
+    /**
+     * Logs warning messages.
+     * @param messages
+     */
+    static warn(...messages) {
+        this._log("warn", ...messages);
+    }
+    /**
+     * Logs error messages.
+     * @param messages
+     */
+    static error(...messages) {
+        this._log("error", ...messages);
+    }
+    /**
+     * Logs info messages.
+     * @param messages
+     */
+    static info(...messages) {
+        this._log("info", ...messages);
+    }
+}
+exports.default = Logger;

package/dist/src/decorators/Entity.d.ts

@@ -0,0 +1,23 @@
+import type DynaRecord from "../DynaRecord";
+/**
+ * A class decorator for marking a class as an entity within the context of the ORM system. This decorator is essential for registering the class as a distinct entity in the ORM's metadata system, enabling the ORM to recognize and manage instances of this class as part of its data model. By designating classes as entities, it facilitates their integration into the ORM framework, allowing for operations such as querying, persisting, and managing relationships between entities.
+ *
+ * IMPORTANT - All entity classes should extend a table class decorated by {@link Table}
+ *
+ * @template T The class being decorated, which extends from the base `DynaRecord` entity class. This ensures that only classes that are part of the ORM system can be decorated as entities.
+ * @param target The constructor function of the class being decorated. This function is used to instantiate objects of the class.
+ * @param context The context in which the decorator is applied, provided by the TypeScript runtime. This includes metadata about the class, such as its kind and other relevant information. The decorator uses this context to perform its registration logic.
+ * @returns {void} The decorator does not return a value. Instead, it performs side effects by registering the class with the ORM's metadata system.
+ *
+ * Usage example:
+ * ```typescript
+ * @Entity
+ * class User extends MyTable {
+ *   // User entity implementation
+ * }
+ * ```
+ * In this example, the `User` class is marked as an entity using the `@Entity` decorator. This designation registers the `User` class within the ORM's metadata system, making it a recognized entity for the ORM to manage. The registration process involves associating the class with its corresponding table name and any additional metadata required by the ORM to handle instances of this class effectively.
+ */
+declare function Entity<T extends DynaRecord>(target: new () => T, context: ClassDecoratorContext): void;
+export default Entity;
+//# sourceMappingURL=Entity.d.ts.map

package/dist/src/decorators/Entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../../src/decorators/Entity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,iBAAS,MAAM,CAAC,CAAC,SAAS,UAAU,EAClC,MAAM,EAAE,UAAU,CAAC,EACnB,OAAO,EAAE,qBAAqB,GAC7B,IAAI,CAKN;AAED,eAAe,MAAM,CAAC"}

package/dist/src/decorators/Entity.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = __importDefault(require("../metadata"));
+/**
+ * A class decorator for marking a class as an entity within the context of the ORM system. This decorator is essential for registering the class as a distinct entity in the ORM's metadata system, enabling the ORM to recognize and manage instances of this class as part of its data model. By designating classes as entities, it facilitates their integration into the ORM framework, allowing for operations such as querying, persisting, and managing relationships between entities.
+ *
+ * IMPORTANT - All entity classes should extend a table class decorated by {@link Table}
+ *
+ * @template T The class being decorated, which extends from the base `DynaRecord` entity class. This ensures that only classes that are part of the ORM system can be decorated as entities.
+ * @param target The constructor function of the class being decorated. This function is used to instantiate objects of the class.
+ * @param context The context in which the decorator is applied, provided by the TypeScript runtime. This includes metadata about the class, such as its kind and other relevant information. The decorator uses this context to perform its registration logic.
+ * @returns {void} The decorator does not return a value. Instead, it performs side effects by registering the class with the ORM's metadata system.
+ *
+ * Usage example:
+ * ```typescript
+ * @Entity
+ * class User extends MyTable {
+ *   // User entity implementation
+ * }
+ * ```
+ * In this example, the `User` class is marked as an entity using the `@Entity` decorator. This designation registers the `User` class within the ORM's metadata system, making it a recognized entity for the ORM to manage. The registration process involves associating the class with its corresponding table name and any additional metadata required by the ORM to handle instances of this class effectively.
+ */
+function Entity(target, context) {
+    if (context.kind === "class") {
+        const tableClassName = Object.getPrototypeOf(target).name;
+        metadata_1.default.addEntity(target, tableClassName);
+    }
+}
+exports.default = Entity;

package/dist/src/decorators/Table.d.ts

@@ -0,0 +1,22 @@
+import { type TableMetadataOptions } from "../metadata";
+import type DynaRecord from "../DynaRecord";
+/**
+ * A class decorator for defining and customizing the table metadata associated with an entity class within the ORM system. This decorator enriches the entity with additional metadata, specifying how the entity relates to the underlying database table. By providing custom table options, such as table names or schema definitions, this decorator plays a crucial role in bridging the gap between the ORM's abstract entities and their concrete database representations.
+ *
+ * IMPORTANT - All entity classes should extend a table
+ *
+ * @param props The {@link TableMetadataOptions} object containing metadata configuration for the table. This can include options like the table's name, delimiter and default field customizations.
+ * @returns A class decorator factory function that takes a target class extending `DynaRecord` and a context object provided by the TypeScript runtime. The decorator function registers the provided metadata options with the ORM's metadata system, ensuring the entity is properly configured and recognized by the ORM.
+ *
+ * Usage example:
+ * ```typescript
+ * @Table({ name: 'my-table', delimiter: '"#",' })
+ * class MyTable extends DynaRecord {
+ *   // User entity implementation
+ * }
+ * ```
+ * In this example, the `@Table` decorator is applied to the `User` class, specifying custom table metadata options, including the table name (`users`) and the schema (`public`). These options are registered with the ORM, which then uses them to correctly map the `User` entity to the corresponding table in the database. This mapping is critical for executing ORM operations such as querying, inserting, and updating records in the `users` table.
+ */
+declare function Table(props: TableMetadataOptions): (target: typeof DynaRecord, context: ClassDecoratorContext) => void;
+export default Table;
+//# sourceMappingURL=Table.d.ts.map