core-transformers

Prefabricated HTML and SQL data transformers for it.rocks primitives and basic types.

This documentation was written by an artificial intelligence and may contain errors or approximations. It has not yet been fully reviewed by a human. If anything seems unclear or incomplete, please feel free to contact the author of this package.

Installation

npm i @itrocks/core-transformers

@itrocks/core-transformers is usually installed together with the it.rocks framework and the low‑level packages @itrocks/transformer, @itrocks/storage, etc. It can also be used on its own in any TypeScript/Node.js project where you need consistent HTML and SQL conversions for primitive values, collections and stored entities.

Usage

This package does not expose UI components directly. Instead, it registers transformers into @itrocks/transformer so that all primitives, collections and stored entities share the same HTML and SQL behaviour across your application.

You normally call one of the provided initialisers once at application startup, then use your usual transformation helpers (for example, those provided by @itrocks/transformer or higher‑level view packages).

Minimal example: initialise everything with default behaviour

import { initCoreTransformers } from '@itrocks/core-transformers'

// At application bootstrap
initCoreTransformers({})

// From this point, any use of the transformer engine for:
// - primitive types (boolean, number, bigint, Date, string),
// - collection properties (`CollectionType`),
// - stored entities (from `@itrocks/storage`),
// will benefit from the default HTML & SQL transformers configured by
// this package.

With this minimal setup, the framework knows how to:

• render HTML form controls for booleans, numbers, dates, text and collections,
• convert submitted data back to typed values,
• adapt booleans and related entities when reading/writing SQL.

Example: customise dependencies and use containers

For a real‑world project you will usually configure a few infrastructure‑specific helpers so that the generated HTML fits your forms (IDs, names, translation, display labels, routes, …) and optionally wrap lists into HTML containers.

import {
  HtmlContainer,
  initCoreTransformers,
  setCorePrimitiveDependencies,
  setStoreDependencies
} from '@itrocks/core-transformers'

// 1. Configure how labels, IDs, names and translations are built
setCorePrimitiveDependencies({
  displayOf:   (object, property) => /* human label for property */,
  fieldIdOf:   property            => `field-${property}`,
  fieldNameOf: property            => property,
  tr:          text                => translate(text)
})

setStoreDependencies({
  displayOf:             (object, property) => /* label for relations */,
  fieldIdOf:             property           => `field-${property}`,
  fieldNameOf:           property           => property,
  representativeValueOf: async object       => object.toString(),
  routeOf:               type               => `/api/${type.name.toLowerCase()}`,
  tr:                    text               => translate(text),
  ignoreTransformedValue: Symbol('ignore')
})

// 2. Register all transformers with the configured dependencies
initCoreTransformers({})

// 3. Later, when asking for HTML output you may request that lists of
//    stored entities are wrapped in containers:

import { HTML } from '@itrocks/transformer'

async function renderList(value: any, transform: Function) {
  const container = new HtmlContainer(true) // enforce container
  const html = await transform(value, HTML, container)
  return String(html)
}

The exact way you ask for a transformation (transform function, pipeline, decorators, …) depends on how you use @itrocks/transformer or higher‑level libraries, but once the initialisation code above has run you get consistent behaviour across the whole application.

API

All exports register or configure transformers in the global @itrocks/transformer registry. They do not return values; their role is to set up the transformation rules used elsewhere.

Core initialiser

initCoreTransformers(dependencies: Partial<Dependencies>): void

Initialises all core transformers in one call:

• primitive transformers (booleans, numbers, bigints, dates, default text fields),
• collection transformers (CollectionType),
• store transformers for entities managed by @itrocks/storage,
• container transformer for HTML wrapping.

dependencies is a composite of the dependency types defined in the sub‑modules collection-type, primitive and store. You usually pass only the properties you want to override; everything else falls back to reasonable defaults.

Call this once during application bootstrap.

Primitive transformers

These functions configure transformers for primitive types and the default behaviour when no specific type is matched.

All of them rely on the dependency helpers defined in setCorePrimitiveDependencies / setPrimitiveDependencies.

initPrimitiveTransformers(dependencies?: Partial<Dependencies>): void

Registers all primitive HTML and SQL transformers at once.

You normally do not need to call it directly if you use initCoreTransformers, but it can be useful in tests or very small projects that only use primitive values.

initBigintHtmlTransformers(): void

Registers an HTML input transformer for JavaScript BigInt values. Values coming from HTML inputs (strings) are converted to BigInt.

initBooleanHtmlTransformers(): void

Registers transformers for boolean values in HTML context:

• EDIT: outputs a label, a hidden 0 field and a checkbox set to 1 when checked.
• INPUT: converts variants of "false" (empty string, 0, localized words for "false"/"no") to false, everything else to true.
• OUTPUT: displays a localized "yes" or "no" string.

initBooleanSqlTransformers(): void

Registers SQL transformers for booleans:

• READ: converts truthy SQL values to true / false.
• SAVE: stores booleans as 0 or 1.

initDateHtmlTransformers(): void

Registers HTML transformers for Date values:

• EDIT: renders a <label> and an <input data-type="date"> with a formatted value when present.
• INPUT: parses a string using your configured parseDate helper.
• OUTPUT: formats a Date using formatDate (or returns an empty string for undefined).

initNumberHtmlTransformers(): void

Registers transformers for numeric values:

• EDIT: renders a <label> and an <input data-type="number">.
• INPUT: accepts localized strings (spaces, comma as decimal separator) and compact suffixes such as "10k", "2M", "1G", … and converts them to a number | undefined.
• OUTPUT: formats the number using the configured precision for the property (via precisionOf) and fr-FR locale.
• READ (SQL): converts SQL values (number | string) to a JavaScript number | undefined.

initDefaultHtmlEditTransformers(): void

Registers a very generic HTML editor used as a fallback when no specific primitive transformer applies. It renders a simple <label> and text <input>.

setCorePrimitiveDependencies(dependencies: Partial<CoreDependencies>): void

Configures the dependencies shared by all primitive transformers except Date:

• displayOf(object, property) – returns the label used in HTML <label> elements.
• fieldIdOf(property) – returns the HTML id attribute for a field.
• fieldNameOf(property) – returns the HTML name attribute for a field.
• tr(text) – translation function used for labels and boolean "yes"/"no" values.

You can call this before initPrimitiveTransformers or initCoreTransformers to integrate these transformers with your own view or i18n layer.

setPrimitiveDependencies(dependencies: Partial<Dependencies>): void

Extends setCorePrimitiveDependencies with the extra date helpers required by the Date transformers:

• formatDate(date: Date): string
• parseDate(text: string): Date

Use this if you want to override both core helpers and date formatting in one place.

Collection transformers

Helpers dedicated to properties of type CollectionType from @itrocks/property-type.

initCollectionHtmlTransformers(dependencies?: Partial<Dependencies>): void

Registers HTML transformers for collections of stored entities.

Generated HTML typically consists of:

• a <label> for the property,
• an unordered list (<ul data-type="objects">) of <input> elements representing the selected entities,
• hidden fields storing the internal IDs used to bind back to your entities.

Dependencies let you control labels, field names/IDs, how each entity is turned into text (representativeValueOf), and how individual property values are rendered inside a table (propertyOutput).

initCollectionTransformers(dependencies?: Partial<Dependencies>): void

Convenience wrapper that currently delegates to initCollectionHtmlTransformers. Provided for symmetry and future extensions.

Container transformers

class HtmlContainer

Small helper object used as a hint when requesting HTML transformations.

• mandatoryContainer: boolean – if true, a container is required.
• container: boolean = true – whether the container is still desired for the current transformation; transformers can set it to false once they have produced their own container.

You typically instantiate HtmlContainer and pass it as the "askFor"/options argument to your transformation function.

initContainerTransformers(): void

Registers a format transformer for HTML that wraps simple values into a <div> when HtmlContainer.mandatoryContainer and HtmlContainer.container are both true. For complex objects, it tries to find the string property whose value matches toString() and wraps only this property.

This is used internally by other transformers when you need HTML containers for values.

Store transformers

These helpers manage the HTML and SQL representations of entities handled by @itrocks/storage.

initStoreHtmlTransformers(target: Type): void

Registers HTML transformers for a given entity Type:

• EDIT: renders an input field with auto‑completion / fetching of related entities plus a hidden field storing the selected ID.
• INPUT: updates the owning object from submitted form data, deciding whether to keep an existing relation, set an ID field (propertyId) or instantiate a new object.
• OUTPUT: displays the representative value of the related entity (representativeValueOf).

initStoreSqlTransformers(target: Type): void

Registers SQL save transformers for the given entity type. When saving, it ensures that the related entity is persisted and that the foreign key <property>_id is set on the SQL record.

initStoreTransformers(target: Type): void

Convenience helper that calls both initStoreHtmlTransformers and initStoreSqlTransformers for the same type.

setStoreDependencies(dependencies: Partial<Dependencies>): void

Configures the helpers used by all store transformers:

• displayOf(object, property) – label for relation fields.
• fieldIdOf(property) / fieldNameOf(property) – build HTML IDs and names.
• representativeValueOf(object) – how to get a display string for an entity.
• routeOf(type) – route used to fetch summaries for auto‑completion.
• tr(text) – translation function.
• ignoreTransformedValue – sentinel value used internally to indicate that an input transformer chose not to alter the original value.

You should set these once, before initialising the store transformers.

setStoreHtmlDependencies(dependencies: Partial<Dependencies>): void

Alias of setStoreDependencies. Provided for readability when you only care about the HTML side.

setStoreSqlDependencies(dependencies: Partial<SqlDependencies>): void

Alias specialised to the SQL‑related subset of dependencies. In practice, this lets you override only ignoreTransformedValue when you need a custom sentinel.

Typical use cases

• Unified form rendering – ensure that all boolean, number, date and text fields across your entities share the same labels, IDs, names, translations and HTML controls.
• Consistent SQL mapping – centralise how booleans, numbers and relations are read from and written to SQL records.
• Collection editing widgets – provide a coherent HTML structure for one‑to‑many or many‑to‑many relations, including list display and inline tables for components.
• Entity relation editors – generate HTML inputs and auto‑complete widgets for relations handled by @itrocks/storage, with transparent synchronisation of foreign keys.
• Framework integration – plug the dependencies into your own routing, translation and display helpers so that the same configuration is reused across multiple projects.