@itrocks/mysql 0.0.5 → 0.0.6

package/README.md

@@ -6,4 +6,136 @@
 
 # mysql
 
-Transforms model objects to and from storage systems.
+Transforms model objects to and from MySQL database records.
+
+## Summary
+
+The `@itrocks/mysql` package provides a seamless integration with MySQL storage, supporting the common
+[@itrocks/storage](https://www.npmjs.com/package/@itrocks/storage) API
+while enabling advanced features for efficient data handling.
+
+## Standard API
+
+The MySQL data source follows the standard [@itrocks/storage](https://www.npmjs.com/package/@itrocks/storage) API.
+For detailed usage, please refer to the [official documentation](https://github.com/itrocks-ts/storage)
+
+## Advanced Features
+
+To fully utilize MySQL storage capabilities, integrate and configure the following advanced features:
+
+### mysqlDependsOn
+
+Configure custom behaviours for MySQL data operations. Example usage (the default):
+```ts
+import { mysqlDependsOn } from '@itrocks/mysql'
+
+mysqlDependsOn({
+	applyReadTransformer:   (record, property) => record[property],
+	applySaveTransformer:   (object, property) => object[property],
+	columnOf:               name => name.toLowerCase(),
+	componentOf:            () => false,
+	ignoreTransformedValue: Symbol('ignoreTransformedValue'),
+	QueryFunction:          class {},
+	queryFunctionCall:      () => [undefined, ' = ?'],
+	storeOf:                target => typeOf(target).name.toLowerCase()
+})
+```
+
+### applyReadTransformer
+
+```ts
+applyReadTransformer: <T extends object>(record: AnyObject, property: KeyOf<T>, object: T) => any
+```
+Transforms a property value when reading data from the database,
+useful for deserialization or type conversion (e.g. string to Date).
+
+**Parameters:**
+- `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)):
+  The data record from MySQL.
+- `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)):
+  The property to transform.
+- `object` (T extends object):
+  The object being constructed.
+  It may be incomplete, as not all properties may have been transformed yet.
+
+**Return value:**
+- The transformed value of `property` to assign to `object`.
+- Alternatively, return [ignoreTransformedValue](#ignoretransformedvalue)
+  to leave the property value unchanged in `object`.
+
+### applySaveTransformer
+
+```ts
+applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, record: AnyObject) => any
+```
+Transforms a property value before saving to the database, e.g., for serialization (Date to string).
+
+**Parameters:**
+- `object` (T extends object):
+  The object being saved.
+- `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)):
+  The property to transform.
+- `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)):
+  The database record to save.
+  It may be incomplete, as not all properties may have been transformed yet.
+
+**Return value:**
+- The transformed value of `property` to assign to `record`.
+- Alternatively, return [ignoreTransformedValue](#ignoretransformedvalue)
+  to exclude the property and its value from `record`.
+
+### columnOf
+
+```ts
+columnOf: (property: string) => string
+```
+Maps a property name to a database column name, enabling custom naming conventions.
+
+### componentOf
+
+```ts
+componentOf: <T extends object>(target: T, property: KeyOf<T>) => boolean
+```
+Determines whether a property represents a tightly bound component relationship (e.g., `one-to-one` or `many-to-one`).
+Defining this function is highly recommended to ensure proper data access from your MySQL relational database.
+
+By default, properties are assumed to represent related collections
+(e.g., `many-to-many` or `one-to-many` relationships).
+
+### ignoreTransformedValue
+
+```ts
+ignoreTransformedValue: any
+```
+This marker value is used to skip property transformation during read or save operations.
+It is returned by your implementation of [applyReadTransformer](#applyreadtransformer)
+and [applySaveTransformer](#applysavetransformer), as needed.
+
+### QueryFunction
+
+```ts
+QueryFunction: Type<QF>
+```
+Specificies a custom query function type for advanced search operations.
+
+### queryFunctionCall
+
+```ts
+queryFunctionCall: (value: QF) => [value: any, sql: string]
+```
+Processes custom query functions, returning the SQL fragment and associated values.
+
+**Parameters:**
+- `value`: An object of a class derived from the one defined by [QueryFunction](#queryfunction).
+
+**Returns:**
+- `value`: The value associated with the query function
+- `sql`: The corresponding SQL fragment 
+
+### storeOf
+
+```ts
+storeOf: <T extends object>(target: ObjectOrType<T>) => string | false
+```
+Maps a class ([ObjectOrType](https://github.com/itrocks-ts/class-type#objectortype))
+to its corresponding database table name, allowing for custom naming conventions.

package/cjs/mysql.d.ts

@@ -6,8 +6,8 @@ import { Identifier, SearchType } from '@itrocks/storage';
 import { Connection } from 'mariadb';
 export declare const DEBUG = false;
 interface Dependencies<QF extends object = object> {
-    applyReadTransformer: <T extends object>(object: T, property: KeyOf<T>, data: AnyObject) => any;
-    applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, data: AnyObject) => any;
+    applyReadTransformer: <T extends object>(record: AnyObject, property: KeyOf<T>, object: T) => any;
+    applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, record: AnyObject) => any;
     columnOf: (property: string) => string;
     componentOf: <T extends object>(target: T, property: KeyOf<T>) => boolean;
     ignoreTransformedValue: any;
@@ -16,6 +16,7 @@ interface Dependencies<QF extends object = object> {
     storeOf: <T extends object>(target: ObjectOrType<T>) => string | false;
 }
 export declare function mysqlDependsOn<QF extends object = object>(dependencies: Partial<Dependencies<QF>>): void;
+export { Mysql };
 export default class Mysql extends DataSource {
     config: {
         host: string;
@@ -49,7 +50,6 @@ export default class Mysql extends DataSource {
     save<T extends object>(object: MayEntity<T>): Promise<Entity<T>>;
     search<T extends object>(type: Type<T>, search?: SearchType<T>): Promise<Entity<T>[]>;
     update<T extends object>(object: Entity<T>): Promise<Entity<T>>;
-    valuesFromDb<T extends object>(row: Entity<T>, type: Type<T>): Promise<Entity<T>>;
-    valuesToDb<T extends object>(object: T, type?: Type<T>): Promise<[AnyObject, Function[]]>;
+    valuesFromDb<T extends object>(record: Entity<T>, type: Type<T>): Promise<Entity<T>>;
+    valuesToDb<T extends object>(object: T): Promise<[AnyObject, Function[]]>;
 }
-export {};

package/cjs/mysql.js

@@ -1,22 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEBUG = void 0;
+exports.Mysql = exports.DEBUG = void 0;
 exports.mysqlDependsOn = mysqlDependsOn;
 const class_type_1 = require("@itrocks/class-type");
+const class_type_2 = require("@itrocks/class-type");
 const reflect_1 = require("@itrocks/reflect");
 const storage_1 = require("@itrocks/storage");
 const mariadb_1 = require("mariadb");
 exports.DEBUG = false;
 const depends = {
-    applyReadTransformer: value => value,
-    applySaveTransformer: value => value,
-    columnOf: name => name,
+    applyReadTransformer: (record, property) => record[property],
+    applySaveTransformer: (object, property) => object[property],
+    columnOf: name => name.toLowerCase(),
     componentOf: () => false,
     ignoreTransformedValue: Symbol('ignoreTransformedValue'),
     QueryFunction: class {
     },
     queryFunctionCall: () => [undefined, ' = ?'],
-    storeOf: () => false
+    storeOf: target => (0, class_type_2.typeOf)(target).name.toLowerCase()
 };
 function mysqlDependsOn(dependencies) {
     Object.assign(depends, dependencies);
@@ -159,8 +160,9 @@ class Mysql extends storage_1.DataSource {
     }
     async search(type, search = {}) {
         const connection = this.connection ?? await this.connect();
+        Object.setPrototypeOf(search, type.prototype);
         const sql = this.propertiesToSearchSql(search);
-        const [values] = await this.valuesToDb(search, type);
+        const [values] = await this.valuesToDb(search);
         if (exports.DEBUG)
             console.log('SELECT * FROM `' + depends.storeOf(type) + '`' + sql, '[', values, ']');
         const rows = await connection.query('SELECT * FROM `' + depends.storeOf(type) + '`' + sql, Object.values(values));
@@ -179,32 +181,32 @@ class Mysql extends storage_1.DataSource {
         }
         return object;
     }
-    async valuesFromDb(row, type) {
+    async valuesFromDb(record, type) {
         const object = (new type);
         let property;
-        for (property in row) {
-            const value = await depends.applyReadTransformer(object, property, row);
+        for (property in record) {
+            const value = await depends.applyReadTransformer(record, property, object);
             if (value === depends.ignoreTransformedValue)
                 continue;
             object[property] = value;
         }
         return object;
     }
-    async valuesToDb(object, type) {
-        const typeObject = type ? new type : object;
+    async valuesToDb(object) {
         const deferred = [];
-        const values = {};
-        for (const property of type ? Object.keys(object) : new reflect_1.ReflectClass(object).propertyNames) {
-            const value = await depends.applySaveTransformer(typeObject, property, values);
+        const record = {};
+        for (const property of Object.keys(object)) {
+            const value = await depends.applySaveTransformer(object, property, record);
             if (value === depends.ignoreTransformedValue)
                 continue;
             if ((0, class_type_1.isAnyFunction)(value)) {
                 deferred.push(value);
                 continue;
             }
-            values[property] = value;
+            record[property] = value;
         }
-        return [values, deferred];
+        return [record, deferred];
     }
 }
 exports.default = Mysql;
+exports.Mysql = Mysql;

package/esm/mysql.d.ts

@@ -6,8 +6,8 @@ import { Identifier, SearchType } from '@itrocks/storage';
 import { Connection } from 'mariadb';
 export declare const DEBUG = false;
 interface Dependencies<QF extends object = object> {
-    applyReadTransformer: <T extends object>(object: T, property: KeyOf<T>, data: AnyObject) => any;
-    applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, data: AnyObject) => any;
+    applyReadTransformer: <T extends object>(record: AnyObject, property: KeyOf<T>, object: T) => any;
+    applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, record: AnyObject) => any;
     columnOf: (property: string) => string;
     componentOf: <T extends object>(target: T, property: KeyOf<T>) => boolean;
     ignoreTransformedValue: any;
@@ -16,6 +16,7 @@ interface Dependencies<QF extends object = object> {
     storeOf: <T extends object>(target: ObjectOrType<T>) => string | false;
 }
 export declare function mysqlDependsOn<QF extends object = object>(dependencies: Partial<Dependencies<QF>>): void;
+export { Mysql };
 export default class Mysql extends DataSource {
     config: {
         host: string;
@@ -49,7 +50,6 @@ export default class Mysql extends DataSource {
     save<T extends object>(object: MayEntity<T>): Promise<Entity<T>>;
     search<T extends object>(type: Type<T>, search?: SearchType<T>): Promise<Entity<T>[]>;
     update<T extends object>(object: Entity<T>): Promise<Entity<T>>;
-    valuesFromDb<T extends object>(row: Entity<T>, type: Type<T>): Promise<Entity<T>>;
-    valuesToDb<T extends object>(object: T, type?: Type<T>): Promise<[AnyObject, Function[]]>;
+    valuesFromDb<T extends object>(record: Entity<T>, type: Type<T>): Promise<Entity<T>>;
+    valuesToDb<T extends object>(object: T): Promise<[AnyObject, Function[]]>;
 }
-export {};

package/esm/mysql.js

@@ -1,22 +1,24 @@
 import { isAnyFunction } from '@itrocks/class-type';
-import { ReflectClass, ReflectProperty } from '@itrocks/reflect';
+import { typeOf } from '@itrocks/class-type';
+import { ReflectProperty } from '@itrocks/reflect';
 import { DataSource } from '@itrocks/storage';
 import { createConnection } from 'mariadb';
 export const DEBUG = false;
 const depends = {
-    applyReadTransformer: value => value,
-    applySaveTransformer: value => value,
-    columnOf: name => name,
+    applyReadTransformer: (record, property) => record[property],
+    applySaveTransformer: (object, property) => object[property],
+    columnOf: name => name.toLowerCase(),
     componentOf: () => false,
     ignoreTransformedValue: Symbol('ignoreTransformedValue'),
     QueryFunction: class {
     },
     queryFunctionCall: () => [undefined, ' = ?'],
-    storeOf: () => false
+    storeOf: target => typeOf(target).name.toLowerCase()
 };
 export function mysqlDependsOn(dependencies) {
     Object.assign(depends, dependencies);
 }
+export { Mysql };
 export default class Mysql extends DataSource {
     config;
     connection;
@@ -155,8 +157,9 @@ export default class Mysql extends DataSource {
     }
     async search(type, search = {}) {
         const connection = this.connection ?? await this.connect();
+        Object.setPrototypeOf(search, type.prototype);
         const sql = this.propertiesToSearchSql(search);
-        const [values] = await this.valuesToDb(search, type);
+        const [values] = await this.valuesToDb(search);
         if (DEBUG)
             console.log('SELECT * FROM `' + depends.storeOf(type) + '`' + sql, '[', values, ']');
         const rows = await connection.query('SELECT * FROM `' + depends.storeOf(type) + '`' + sql, Object.values(values));
@@ -175,31 +178,30 @@ export default class Mysql extends DataSource {
         }
         return object;
     }
-    async valuesFromDb(row, type) {
+    async valuesFromDb(record, type) {
         const object = (new type);
         let property;
-        for (property in row) {
-            const value = await depends.applyReadTransformer(object, property, row);
+        for (property in record) {
+            const value = await depends.applyReadTransformer(record, property, object);
             if (value === depends.ignoreTransformedValue)
                 continue;
             object[property] = value;
         }
         return object;
     }
-    async valuesToDb(object, type) {
-        const typeObject = type ? new type : object;
+    async valuesToDb(object) {
         const deferred = [];
-        const values = {};
-        for (const property of type ? Object.keys(object) : new ReflectClass(object).propertyNames) {
-            const value = await depends.applySaveTransformer(typeObject, property, values);
+        const record = {};
+        for (const property of Object.keys(object)) {
+            const value = await depends.applySaveTransformer(object, property, record);
             if (value === depends.ignoreTransformedValue)
                 continue;
             if (isAnyFunction(value)) {
                 deferred.push(value);
                 continue;
             }
-            values[property] = value;
+            record[property] = value;
         }
-        return [values, deferred];
+        return [record, deferred];
     }
 }

package/package.json

@@ -10,7 +10,7 @@
 		"mariadb": "^3.4",
 		"typescript": "~5.6"
 	},
-	"description": "Transforms model objects to and from mysql records",
+	"description": "Transforms model objects to and from MySQL database records",
 	"devDependencies": {
 		"@types/node": "^22.10"
 	},
@@ -58,5 +58,5 @@
 		"build:esm": "tsc -p tsconfig.esm.json"
 	},
 	"types": "./esm/mysql.d.ts",
-	"version": "0.0.5"
+	"version": "0.0.6"
 }