Skip to main content

Using transformers

What you'll learn
  • Using built-in transformers
  • Creating transformers

Built-in transformers​

toDateTime​

toDateTime converts values to Date object using Date.parse. It will serialize values to an ISO date and time string.

import { attr, makeModel, toDateTime } from '@foscia/core';

makeModel('posts', {
  createdAt: attr(toDateTime()),
});
info

toDateTime will log a warning if a value gets converted to an invalid date.

toDate​

toDate converts values to Date object using a custom parser. It expects date to be formatted as ISO date string (YYYY-MM-DD, e.g. 2023-12-25). It will serialize values to an ISO string date with the same format.

import { attr, makeModel, toDate } from '@foscia/core';

makeModel('users', {
  birthday: attr(toDate()),
});
info

toDate will log a warning if a value gets converted to an invalid date.

toDate will also apply an "epoch shift" because serializing to a UTC date. This will avoid local date to be serialized to incorrect date due to UTC serialization.

toNumber​

toNumber converts values to Number object using Number().

import { attr, makeModel, toNumber } from '@foscia/core';

makeModel('products', {
  price: attr(toNumber()),
});
info

toNumber will log a warning if a value gets converted to a NaN value.

toBoolean​

toBoolean converts values to boolean if the value match a truthy value.

You can provide your own truthy values using trueValues option (defaults are [true, 1, '1', 'true', 'yes']).

import { attr, makeModel, toBoolean } from '@foscia/core';

makeModel('users', {
  verified: attr(toBoolean()),
  blocked: attr(toBoolean({ trueValues: [true] })),
});
info

toBoolean won't convert null values.

toString​

toString converts values to String object using String().

import { attr, makeModel, toString } from '@foscia/core';

makeModel('posts', {
  title: attr(toString()),
});
info

toBoolean won't convert null values.

toArrayOf​

toArrayOf converts values of an array using the given transformer. This can be useful when dealing with array of dates.

import { attr, makeModel, toArrayOf, toDateTime } from '@foscia/core';

makeModel('posts', {
  openingDates: attr(toArrayOf(toDateTime())),
});

Creating transformers​

You can generate a new transformer using @foscia/cli.

npx foscia make transformer toDateTime

Foscia provides a makeTransformer utility function to create a new transformer. This function creates a transformer using a deserialize function and an optional serialize function (deserializer will be used as a default).

Transformers created with makeTransformer will transform null or undefined value to null.

Here are two examples of transformers:

transformers/toNumber.ts
import { makeTransformer } from '@foscia/core';

export default () => makeTransformer((value: string) => Number(value));
transformers/toDateTime.ts
import { makeTransformer } from '@foscia/core';

export default () => makeTransformer(
  (value: string) => {
    const date = new Date();
    date.setTime(Date.parse(value));

    return date;
  },
  (value: Date) => value.toISOString(),
);

The return value of makeTransformer is a transformer object.

import { attr, makeModel } from '@foscia/core';
import toNumber from '../transformers/toNumber';
import toDateTime from '../transformers/toDateTime';

makeModel('posts', {
  commentsCount: attr(toNumber()),
  publishedAt: attr(toDateTime()),
});

Custom transformers​

If you want full control on your transformers, you can create transformer objects manually. A transformer object should have two methods:

  • serialize which converts a real value to its raw counterpart
  • deserialize which converts a raw value to its real counterpart
export default {
  deserialize: (value: string | null) => {
    if (value === null) {
      return null;
    }

    const date = new Date();
    date.setTime(Date.parse(value));

    return date;
  },
  serialize: (value: Date | null) => (value ? value.toISOString() : null),
};
warning

Custom transformers must handle null values because null may also be transformed by serializers and deserializers (e.g. converting a null value to an empty string).