Docs · npm
Node.js
El paquete donly es un módulo ESM con tipos de
TypeScript. Permite parsear texto DON, recorrer y buscar directivas, convertirlas
a JSON, validarlas con reglas de lint y extender el parseo con plugins.
Instalación
$ npm i donly
$ bun add donly
El manifiesto declara bun >=1.0.0 en
engines y los scripts del proyecto usan Bun, pero
el paquete es un módulo ESM que también se importa desde Node.js. Los ejemplos
de esta página se ejecutaron con Node.js 22.
Parsear un documento
Todos los ejemplos usan este documento app.donly:
name "my-app"
port 8080
enabled true
server {
host "example.com"
route GET /home {
respond 200
}
route POST /api/user
} DON.parse(text) devuelve una
Directive. Con varias directivas de primer
nivel devuelve una raíz sintética (su nombre es el símbolo
ROOT_DIRECTIVE_NAME) que las contiene como
children. Con una sola, devuelve esa
directiva.
import { DON } from "donly";
const root = DON.parse(text);
for (const directive of root.children) {
console.log(directive.name, directive.args);
}
// name [ 'my-app' ]
// port [ 8080 ]
// enabled [ true ]
// server []Directive
-
name:string | symbol. -
args: lista denumber | string | boolean | HeredocValue. -
children: directivas del bloque. -
parent: la directiva que la contiene, oundefined. -
toJSON(),find(),findAll()yat().
Buscar directivas
find devuelve la primera coincidencia,
findAll todas, y
at permite terminar el camino en
[N] para obtener un argumento. Las posiciones
empiezan en 1. Los grupos ( ) comparan todos los
argumentos de la directiva, y { } filtra por
descendientes.
root.find("/server/host")?.args; // [ 'example.com' ]
root.at("/server/host[1]"); // 'example.com'
root.findAll("/server/route").length; // 2
// Una directiva con hijos que cumplan un camino
root.findAll("/server/route{/respond}").length; // 1
// Coincidencia completa de los argumentos
root.findAll("/server/route(GET /home)").length; // 1
root.findAll("/server/route(* /api/user)").length; // 1
Las mismas funciones están disponibles como
findDirective,
findAllDirectives y
atDirective en
donly/find.
Convertir a JSON
JSON.stringify usa
toJSON, que agrupa por el primer argumento (tupleReducer). Con
DirectiveJSONEncoder eliges el reducer:
nestedReducer anida cada argumento como una clave, y
reducer: null devuelve la forma completa
{ name, args, children }.
import { DON, DirectiveJSONEncoder } from "donly";
JSON.stringify(root);
// {"name":"my-app","port":8080,"enabled":true,
// "server":{"host":"example.com",
// "route":[["GET","/home",{"respond":200}],["POST","/api/user"]]}}
DirectiveJSONEncoder.encode(root, {
reducer: DirectiveJSONEncoder.nestedReducer,
});
// {"name":"my-app","port":8080,"enabled":true,
// "server":{"host":"example.com",
// "route":[{"GET":{"/home":{"respond":200}}},{"POST":"/api/user"}]}}Cargar un archivo
load lee el archivo y devuelve un objeto plano
con el reducer anidado.
import { load } from "donly/load";
const config = await load("./app.donly");
// { name: 'my-app', port: 8080, enabled: true, server: { ... } }Errores de sintaxis
Un documento inválido hace que DON.parse lance
un error con el motivo.
import { DON } from "donly";
try {
DON.parse('container { image "nginx" } extra');
} catch (error) {
console.error(error.message);
// Syntax error: tokens after block close are not allowed on the same line (found "extra")
}Lint
lint(text, rules) valida un documento contra un
objeto de reglas y devuelve una lista de
issues (vacía si todo es válido).
renderReport la formatea para la terminal y
renderJSONReport en JSON. Las reglas también pueden
escribirse en un archivo .donly y cargarse con
parseLintRulesDonly. La CLI
npx donly lint usa esta misma API.
import { lint, renderReport } from "donly/lint";
const rules = {
"/": {
"/port": { "[1]": { type: "string" } },
},
};
const issues = lint(text, rules);
console.log(renderReport(issues, { filePath: "app.donly" }));
// app.donly
// 2:6 error argument at position 1 must be of type string
//
// 1 error 0 warnings 0 infoPlugins
DON.parse(text, { plugins }) acepta una lista
de DonPlugin. Cada plugin tiene un
name y puede definir
initContext, para crear su estado en cada
parseo, y onDirective, que recibe cada
directiva en orden de lectura. Puede devolver un nodo nuevo para cambiar sus
argumentos o null para eliminarla junto con sus hijos.
Importaciones
| Módulo | Exporta |
|---|---|
| donly | DON, Directive, HeredocValue, DirectiveJSONEncoder, DirectiveJSONDecoder, ROOT_DIRECTIVE_NAME, SyntaxEncode, LexerParser, SyntaxKind, donToParts |
| donly/load | load(filePath): lee un archivo y devuelve un objeto |
| donly/find | findDirective, findAllDirectives, atDirective |
| donly/encoder | DirectiveJSONEncoder |
| donly/decoder | DirectiveJSONDecoder |
| donly/utils | inspect(directive, strategy) |
| donly/demo/plugins/variables | variablesPlugin (demo) |
| donly/demo/plugins/resources | createResourcesPlugin (demo) |
| donly/demo/http-proxy | serve, proxyLintRules (demo) |
| donly/lint | lint, parseLintRulesDonly, renderReport, renderJSONReport |
| donly/common/errors | DonSyntaxError |
| donly/plugins/scoped-variables | scopedVariablesPlugin, createScopedVariablesPlugin |
Referencia
- DON parse y errores de sintaxis
- Directive el nodo del árbol
- SyntaxKind tokens y utilidades de bajo nivel
- Plugin extender el parseo
- scoped-variables variables con alcance por bloque
- Rutas la sintaxis de find, findAll, at y reglas de lint
- Lint validar documentos con reglas
- Demo http-proxy proxy inverso con recarga en caliente