Fonctions personnalisées

Typeflow embarque une bibliothèque standard de niveau JSONata aux signatures typées (voir Fonctions), plus des déclarations use pour amener vos propres fonctions TypeScript dans un mapping. Fonction inconnue : TF2007 ; mauvais types d'arguments : TF2008 — les deux à la compilation.

Quand la bibliothèque standard ne suffit pas, définissez vos propres fonctions. Les trois variantes sont vérifiées à la compilation exactement comme les natives — nom inconnu, mauvaise arité et mauvais types d'arguments sont des erreurs de compilation.

Dans le langage : fn

Définissez des fonctions pures directement dans le mapping — le corps est une expression Typeflow sur les paramètres (l'input n'est pas dans la portée, les fonctions restent donc réutilisables et indépendantes de leur position). Le type de retour est optionnel : il est inféré depuis le corps, et vérifié (TF2017) quand il est déclaré. Une fonction peut appeler les natives et les fonctions déclarées avant elle — pas de référence avant déclaration, les mappings restent donc terminants.

Entièrement sérialisable : les définitions fn voyagent dans l'artefact compilé, elles fonctionnent donc partout où le runtime tourne — y compris ici même :

Mapping✔Playground ↗

input user: { first: string, last: string, scores: number[] }

fn fullName(first: string, last: string): string = first + " " + last
fn grade(score: number) = score >= 15 ? "A" : score >= 10 ? "B" : "C"

map {
  name: fullName(user.first, user.last),
  grades: user.scores -> { value: $, grade: grade($) },
}

input user: { first: string, last: string, scores: number[] } fn fullName(first: string, last: string): string = first + " " + last fn grade(score: number) = score >= 15 ? "A" : score >= 10 ? "B" : "C" map { name: fullName(user.first, user.last), grades: user.scores -> { value: $, grade: grade($) }, }

JSON d'entrée

{ "first": "Ada", "last": "Lovelace", "scores": [16, 9, 12] }

{ "first": "Ada", "last": "Lovelace", "scores": [16, 9, 12] }

Sortie

{
  "name": "Ada Lovelace",
  "grades": [
    {
      "value": 16,
      "grade": "A"
    },
    {
      "value": 9,
      "grade": "C"
    },
    {
      "value": 12,
      "grade": "B"
    }
  ]
}

type inféré{ name: string; grades: { value: number; grade: "A" | "B" | "C" }[]; }

Depuis TypeScript : use

Déclarez la signature typée dans le fichier .typeflow ; l'implémentation est importée depuis le module au chargement du mapping :

use slugify(value: string): string from "./helpers"

// helpers
export function slugify(value: string): string {
  return value.toLowerCase().replace(/[^a-z0-9]+/g, '-');
}

loadTypeflowMapping("./user.typeflow") et typeflow run importent ./helpers automatiquement. Avec l'API bas niveau du runtime, passez les implémentations explicitement — l'instanciation échoue immédiatement s'il en manque une :

createMapping(compiled, { functions: { slugify } });

Depuis votre application : defineFunction

Enregistrez des fonctions une fois, côté application — aucune ligne use nécessaire dans les mappings. Une définition se déclare comme une native : signature typée, doc, implémentation :

import { defineFunction, compile, createMapping } from 'typeflowjs';

const slugify = defineFunction('slugify(value: string): string', {
  doc: 'Slug en minuscules, séparé par des tirets.',
  impl: (value) => String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-'),
});

const result = compile(source, { functions: [slugify] });
const run = createMapping(result.compiled!, { functions: [slugify] });

Les paramètres optionnels fonctionnent (clamp(n: number, max?: number): number), l'artefact compilé enregistre quelles fonctions le mapping appelle réellement, et createMapping échoue immédiatement s'il en manque une. loadTypeflowMapping(path, { functions }) les accepte aussi.

Essayez en direct

Le playground ne peut pas importer de fichiers, il fournit donc deux implémentations de démonstration : slugify et capitalize (notez le ? — les paramètres optionnels sont pris en charge) :

Mapping✔Playground ↗

input user: { firstName: string, lastName: string }

use slugify(value: string): string from "./helpers"
use capitalize(value: string): string from "./helpers"

map {
  handle: slugify(user.firstName + " " + user.lastName),
  display: capitalize(user.firstName),
}

input user: { firstName: string, lastName: string } use slugify(value: string): string from "./helpers" use capitalize(value: string): string from "./helpers" map { handle: slugify(user.firstName + " " + user.lastName), display: capitalize(user.firstName), }

JSON d'entrée

{ "firstName": "ada", "lastName": "Lovelace" }

{ "firstName": "ada", "lastName": "Lovelace" }

Sortie

{
  "handle": "ada-lovelace",
  "display": "Ada"
}

type inféré{ handle: string; display: string }

Les signatures sont imposées comme pour les natives — essayez slugify(42) ci-dessus (TF2008), ou renommez un use en upper (TF2016 : conflit avec une native).

Cet exemple est volontairement cassé

Une fonction inconnue est une erreur de compilation, et le diagnostic liste ce qui est disponible :

Mapping✖ 1Playground ↗

input user: { name: string }

map {
  name: capitalizeWords(user.name),
}

input user: { name: string } map { name: capitalizeWords(user.name), }

JSON d'entrée

{ "name": "ada lovelace" }

{ "name": "ada lovelace" }

Sortie

// Corrigez les erreurs du mapping pour voir la sortie.

type inféré{ name: any }

• 4:9errorTF2007Unknown function 'capitalizeWords'.
  indice: Available functions: string, length, contains, matches, upper, lower, trim, pad, substring, split, replace, base64encode, base64decode, encodeUrl, decodeUrl, encodeUrlComponent, decodeUrlComponent, number, formatBase, floor, ceil, round, abs, power, sqrt, random, sum, max, min, average, boolean, not, exists, count, join, append, zip, sort, reverse, shuffle, distinct, keys, values, lookup, merge, spread, type, now, millis, fromMillis, toMillis.