@itrocks/mysql 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +60 -69
  2. package/cjs/mysql.js +2 -2
  3. package/esm/mysql.js +2 -2
  4. package/package.json +3 -1
package/README.md CHANGED
@@ -1,141 +1,132 @@
1
- [![npm version](https://img.shields.io/npm/v/@itrocks/mysql?logo=npm)](https://www.npmjs.org/package/@itrocks/mysql)
2
- [![npm downloads](https://img.shields.io/npm/dm/@itrocks/mysql)](https://www.npmjs.org/package/@itrocks/mysql)
3
- [![GitHub](https://img.shields.io/github/last-commit/itrocks-ts/mysql?color=2dba4e&label=commit&logo=github)](https://github.com/itrocks-ts/mysql)
4
- [![issues](https://img.shields.io/github/issues/itrocks-ts/mysql)](https://github.com/itrocks-ts/mysql/issues)
5
- [![discord](https://img.shields.io/discord/1314141024020467782?color=7289da&label=discord&logo=discord&logoColor=white)](https://25.re/ditr)
6
-
7
1
  # mysql
8
2
 
9
3
  Transforms model objects to and from MySQL database records.
10
4
 
11
5
  ## Summary
12
6
 
13
- The `@itrocks/mysql` package provides a seamless integration with MySQL storage, supporting the common
14
- [@itrocks/storage](https://www.npmjs.com/package/@itrocks/storage) API
15
- while enabling advanced features for efficient data handling.
7
+ The `@itrocks/mysql` package provides integration with MySQL storage and implements the
8
+ standard [@itrocks/storage](https://www.npmjs.com/package/@itrocks/storage) `DataSource` API.
16
9
 
17
10
  ## Standard API
18
11
 
19
12
  The MySQL data source follows the standard [@itrocks/storage](https://www.npmjs.com/package/@itrocks/storage) API.
20
- For detailed usage, please refer to the [official documentation](https://github.com/itrocks-ts/storage)
13
+ Refer to the [storage documentation](https://github.com/itrocks-ts/storage) for generic behaviours.
21
14
 
22
15
  ## Advanced Features
23
16
 
24
- To fully utilize MySQL storage capabilities, integrate and configure the following advanced features:
17
+ To fully utilise MySQL storage capabilities, integrate and configure the following advanced dependency features:
25
18
 
26
19
  ### mysqlDependsOn
27
20
 
28
- Configure custom behaviours for MySQL data operations. Example usage (the default):
21
+ Configure custom behaviours for MySQL data operations.
22
+
29
23
  ```ts
30
24
  import { mysqlDependsOn } from '@itrocks/mysql'
31
25
 
32
26
  mysqlDependsOn({
33
- applyReadTransformer: (record, property) => record[property],
34
- applySaveTransformer: (object, property) => object[property],
35
- columnOf: name => name.toLowerCase(),
36
- componentOf: () => false,
37
- ignoreTransformedValue: Symbol('ignoreTransformedValue'),
38
- QueryFunction: class {},
39
- queryFunctionCall: () => [undefined, ' = ?'],
40
- storeOf: target => typeOf(target).name.toLowerCase()
27
+ applyReadTransformer: (record, property) => record[property],
28
+ applySaveTransformer: (object, property) => object[property],
29
+ columnOf: name => name.toLowerCase(),
30
+ componentOf: () => false,
31
+ ignoreTransformedValue: Symbol('ignoreTransformedValue'),
32
+ QueryFunction: class {},
33
+ queryFunctionCall: () => [undefined, ' = ?'],
34
+ storeOf: target => target.constructor.name.toLowerCase()
41
35
  })
42
36
  ```
43
37
 
44
38
  ### applyReadTransformer
45
39
 
46
40
  ```ts
47
- applyReadTransformer: <T extends object>(record: AnyObject, property: KeyOf<T>, object: T) => any
41
+ <T extends object>(record: AnyObject, property: KeyOf<T>, object: T) => any
48
42
  ```
49
- Transforms a property value when reading data from the database,
50
- useful for deserialization or type conversion (e.g. string to Date).
43
+
44
+ Transforms a property value when reading data from the database, e.g. for deserialization (string to Date).
51
45
 
52
46
  **Parameters:**
53
- - `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)):
54
- The data record from MySQL.
55
- - `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)):
56
- The property to transform.
57
- - `object` (T extends object):
58
- The object being constructed.
59
- It may be incomplete, as not all properties may have been transformed yet.
60
-
61
- **Return value:**
47
+ - `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)): The data record from MySQL.
48
+ - `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)): The name of the property.
49
+ - `object` (`T extends object`): The object the property value must be written to. It may be partially initialised.
50
+
51
+ **Returns:**
62
52
  - The transformed value of `property` to assign to `object`.
63
- - Alternatively, return [ignoreTransformedValue](#ignoretransformedvalue)
64
- to leave the property value unchanged in `object`.
53
+ - Returning [ignoreTransformedValue](#ignoretransformedvalue) leaves the property unchanged.
65
54
 
66
55
  ### applySaveTransformer
67
56
 
68
57
  ```ts
69
- applySaveTransformer: <T extends object>(object: T, property: KeyOf<T>, record: AnyObject) => any
58
+ <T extends object>(object: T, property: KeyOf<T>, record: AnyObject) => any
70
59
  ```
71
- Transforms a property value before saving to the database, e.g., for serialization (Date to string).
60
+
61
+ Transforms a property value before saving to the database, e.g. for serialization (Date to string).
72
62
 
73
63
  **Parameters:**
74
- - `object` (T extends object):
75
- The object being saved.
76
- - `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)):
77
- The property to transform.
78
- - `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)):
79
- The database record to save.
80
- It may be incomplete, as not all properties may have been transformed yet.
81
-
82
- **Return value:**
64
+ - `object` (`T extends object`): The object which property value must be transformed.
65
+ - `property` ([KeyOf&lt;T&gt;](https://github.com/itrocks-ts/class-type#keyof)): The name of the property.
66
+ - `record` ([AnyObject](https://github.com/itrocks-ts/class-type#anyobject)): The data record for MySQL writing.
67
+ It may be partially set.
68
+
69
+ **Returns:**
83
70
  - The transformed value of `property` to assign to `record`.
84
- - Alternatively, return [ignoreTransformedValue](#ignoretransformedvalue)
85
- to exclude the property and its value from `record`.
71
+ - Returning [ignoreTransformedValue](#ignoretransformedvalue) excludes the property from persistence.
72
+ - Returning an array schedules a collection save.
73
+ - Returning a function schedules a deferred operation.
74
+
75
+ **Deferred operation** (returning a function):
76
+
77
+ When `applySaveTransformer()` returns a **function**, it is not written to the SQL record.\
78
+ Instead, it is stored and executed after the object save operation completes.
79
+
80
+ The callback will receive the persisted `object` as first argument.
86
81
 
87
82
  ### columnOf
88
83
 
89
84
  ```ts
90
- columnOf: (property: string) => string
85
+ (property: string) => string
91
86
  ```
92
- Maps a property name to a database column name, enabling custom naming conventions.
87
+
88
+ Maps an object property name to a database column name.
93
89
 
94
90
  ### componentOf
95
91
 
96
92
  ```ts
97
- componentOf: <T extends object>(target: T, property: KeyOf<T>) => boolean
93
+ <T extends object>(target: T, property: KeyOf<T>) => boolean
98
94
  ```
99
- Determines whether a property represents a tightly bound component relationship (e.g., `one-to-one` or `many-to-one`).
100
- Defining this function is highly recommended to ensure proper data access from your MySQL relational database.
101
95
 
102
- By default, properties are assumed to represent related collections
103
- (e.g., `many-to-many` or `one-to-many` relationships).
96
+ Indicates whether a collection property is stored as components (one-to-many / owned) instead of a link table.
104
97
 
105
98
  ### ignoreTransformedValue
106
99
 
107
- ```ts
108
- ignoreTransformedValue: any
109
- ```
110
- This marker value is used to skip property transformation during read or save operations.
111
- It is returned by your implementation of [applyReadTransformer](#applyreadtransformer)
112
- and [applySaveTransformer](#applysavetransformer), as needed.
100
+ Marker value used by transformers to prevent persistence or assignment after the callback is executed.
113
101
 
114
102
  ### QueryFunction
115
103
 
116
104
  ```ts
117
- QueryFunction: Type<QF>
105
+ Type<QF>
118
106
  ```
119
- Specificies a custom query function type for advanced search operations.
107
+
108
+ Base class for custom query functions.
120
109
 
121
110
  ### queryFunctionCall
122
111
 
123
112
  ```ts
124
- queryFunctionCall: (value: QF) => [value: any, sql: string]
113
+ (value: QF) => [any, string]
125
114
  ```
126
- Processes custom query functions, returning the SQL fragment and associated values.
115
+
116
+ Converts a query function into a SQL fragment and its bound value.
127
117
 
128
118
  **Parameters:**
129
119
  - `value`: An object of a class derived from the one defined by [QueryFunction](#queryfunction).
130
120
 
131
121
  **Returns:**
132
- - `value`: The value associated with the query function
133
- - `sql`: The corresponding SQL fragment
122
+ - `any`: The value associated with the query function
123
+ - `string`: The corresponding SQL fragment
134
124
 
135
125
  ### storeOf
136
126
 
137
127
  ```ts
138
- storeOf: <T extends object>(target: ObjectOrType<T>) => string | false
128
+ <T extends object>(target: ObjectOrType<T>) => string | false
139
129
  ```
140
- Maps a class ([ObjectOrType](https://github.com/itrocks-ts/class-type#objectortype))
141
- to its corresponding database table name, allowing for custom naming conventions.
130
+
131
+ Maps a [class or object](https://github.com/itrocks-ts/class-type#objectortype) to its table name.
132
+ Returning `false` disables persistence for that type.
package/cjs/mysql.js CHANGED
@@ -99,7 +99,7 @@ class Mysql extends storage_1.DataSource {
99
99
  const id = result.insertId;
100
100
  const entity = this.connectObject(object, ((id >= Number.MIN_SAFE_INTEGER) && (id <= Number.MAX_SAFE_INTEGER)) ? Number(id) : id);
101
101
  for (const callback of deferred) {
102
- callback(object);
102
+ await callback(object);
103
103
  }
104
104
  return entity;
105
105
  }
@@ -359,7 +359,7 @@ class Mysql extends storage_1.DataSource {
359
359
  console.log(query, JSON.stringify(Object.values(values).concat([object.id])));
360
360
  await connection.query(query, Object.values(values).concat([object.id]));
361
361
  for (const callback of deferred) {
362
- callback(object);
362
+ await callback(object);
363
363
  }
364
364
  return object;
365
365
  }
package/esm/mysql.js CHANGED
@@ -94,7 +94,7 @@ export class Mysql extends DataSource {
94
94
  const id = result.insertId;
95
95
  const entity = this.connectObject(object, ((id >= Number.MIN_SAFE_INTEGER) && (id <= Number.MAX_SAFE_INTEGER)) ? Number(id) : id);
96
96
  for (const callback of deferred) {
97
- callback(object);
97
+ await callback(object);
98
98
  }
99
99
  return entity;
100
100
  }
@@ -354,7 +354,7 @@ export class Mysql extends DataSource {
354
354
  console.log(query, JSON.stringify(Object.values(values).concat([object.id])));
355
355
  await connection.query(query, Object.values(values).concat([object.id]));
356
356
  for (const callback of deferred) {
357
- callback(object);
357
+ await callback(object);
358
358
  }
359
359
  return object;
360
360
  }
package/package.json CHANGED
@@ -5,6 +5,8 @@
5
5
  },
6
6
  "dependencies": {
7
7
  "@itrocks/class-type": "latest",
8
+ "@itrocks/composition": "latest",
9
+ "@itrocks/property-type": "latest",
8
10
  "@itrocks/reflect": "latest",
9
11
  "@itrocks/sort": "latest",
10
12
  "@itrocks/storage": "latest",
@@ -59,5 +61,5 @@
59
61
  "build:esm": "tsc -p tsconfig.esm.json"
60
62
  },
61
63
  "types": "./esm/mysql.d.ts",
62
- "version": "0.1.3"
64
+ "version": "0.1.4"
63
65
  }