Docs · npm

TypeScript

donly incluye sus propios tipos (.d.ts); no necesitas instalar @types. Esta página reúne lo específico de TypeScript. El resto de la API está en Node.js.

Configuración

El paquete es ESM y expone submódulos como donly/lint o donly/find mediante exports. Para que TypeScript los resuelva, usa un moduleResolution que soporte exports: NodeNext, Node16 o Bundler.

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}

Los ejemplos de esta página compilan sin errores con TypeScript 7.0.2 en modo strict, con esas tres opciones de moduleResolution.

Importaciones

Los tipos y las clases salen de los mismos módulos que en JavaScript. Usa import type (o type en línea) para lo que solo es un tipo.

import { DON, Directive, HeredocValue } from "donly";
import type { DonPlugin, PluginDirectiveNode, DONParseOptions } from "donly";
import { lint } from "donly/lint";
import type { LintRuleDocument, LintIssue } from "donly/lint";
import { atDirective, findDirective } from "donly/find";
import type { AtPathResult } from "donly/find";
import type { InspectStrategy } from "donly/utils";

Tipos de los argumentos

Directive.args es (number | string | boolean | HeredocValue)[]. Se estrecha con typeof e instanceof.

const root = DON.parse('title "hola"');

for (const arg of root.args) {
  if (arg instanceof HeredocValue) {
    arg.content.toUpperCase(); // HeredocValue
  } else if (typeof arg === "string") {
    arg.toUpperCase();         // string
  } else if (typeof arg === "number") {
    arg.toFixed();             // number
  }                            // boolean en el resto
}

at() tipado

El tipo de retorno de at depende de la ruta cuando es un literal: con [N] al final devuelve el valor del argumento y, si no, la directiva. Ambos casos incluyen undefined, así que TypeScript te obliga a manejar que no exista.

const root = DON.parse('server { host "example.com" }');

// Con [N] al final, el tipo es el del argumento
const host = root.at("/server/host[1]");
//    ^ string | number | boolean | HeredocValue | undefined

// Sin [N], es la directiva
const node = root.at("/server/host");
//    ^ Directive | undefined

// Una ruta que no es un literal no se puede resolver en compilación
declare const path: string;
const unknown = root.at(path);
//    ^ Directive | argumento | undefined

const port: number = root.at("/server/port[1]");
// Error: Type 'undefined' is not assignable to type 'number'

Plugins

DonPlugin<TContext> tipa el estado que crea initContext y que reciben los demás hooks.

import { DON, type DonPlugin } from "donly";

interface Context {
  seen: string[];
}

const seen: DonPlugin<Context> = {
  name: "seen",
  initContext: () => ({ seen: [] }),
  onDirective(node, ctx) {
    ctx.seen.push(String(node.name)); // ctx: Context
  },
};

DON.parse(text, { plugins: [seen] });

Reglas de lint

LintRuleDocument valida la forma de las reglas mientras las escribes.

import { lint, type LintRuleDocument } from "donly/lint";

const rules: LintRuleDocument = {
  "/port": { "[1]": { type: "number", gte: 1, lte: 65535 } },
};

const issues = lint(text, rules); // LintIssue[]

Estos casos son errores de compilación:

const a: LintRuleDocument = {
  "/port": { severity: "fatal" },
  // Error: "fatal" no es "error" | "warning" | "info"
};

const b: LintRuleDocument = {
  port: {},
  // Error: las claves de ruta deben empezar con "/"
};

const c: DonPlugin = {
  onDirective() {},
  // Error: falta la propiedad "name"
};

Tipos exportados

Módulo	Tipos
donly	Directive, HeredocValue, DONParseOptions, DonPlugin, PluginDirectiveNode, Token, DirectiveReducer, DirectiveJSONEncoderOptions
donly/find	AtPathResult
donly/utils	InspectStrategy
donly/lint	LintRuleDocument, LintRuleArray, RuleBody, ArgumentConstraint, StringArgumentConstraint, NumberArgumentConstraint, BigintArgumentConstraint, BooleanArgumentConstraint, NullArgumentConstraint, HeredocArgumentConstraint, ArgumentType, RuleSeverity, LintIssue, LintSeverity, LintLoc, RenderReportOptions, RenderJSONReportOptions, JSONReport, JSONReportIssue