mysql

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 API while enabling advanced features for efficient data handling.

Standard API

The MySQL data source follows the standard @itrocks/storage API. For detailed usage, please refer to the official documentation

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):

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

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): The data record from MySQL.
• property (KeyOf<T>): 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 to leave the property value unchanged in object.

applySaveTransformer

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<T>): The property to transform.
• record (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 to exclude the property and its value from record.

columnOf

columnOf: (property: string) => string

Maps a property name to a database column name, enabling custom naming conventions.

componentOf

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

ignoreTransformedValue: any

This marker value is used to skip property transformation during read or save operations. It is returned by your implementation of applyReadTransformer and applySaveTransformer, as needed.

QueryFunction

QueryFunction: Type<QF>

Specificies a custom query function type for advanced search operations.

queryFunctionCall

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.

Returns:

• value: The value associated with the query function
• sql: The corresponding SQL fragment

storeOf

storeOf: <T extends object>(target: ObjectOrType<T>) => string | false

Maps a class (ObjectOrType) to its corresponding database table name, allowing for custom naming conventions.