🧬 DTL Parser (JavaScript/TypeScript)

Parser for DTL (Domain Transport Language) - Ultra-compact, schema-driven, cryptographic data transport format for JavaScript and TypeScript.

📖 Specification: dtlaz.org | 🌐 AlifZetta: axz.si

Installation

npm install dtl-parser
# or
yarn add dtl-parser
# or
pnpm add dtl-parser

Quick Start

import { parse, write, createDocument, addTable } from 'dtl-parser';

// Parse DTL content
const doc = parse(`
@dtlv1.0^dtHC^pMedical^c1^s0^w0^h0
@sec^hash^0x0^none^0

PATIENTS|id:s,name:s,age:i|2|S0|W0|C1
P001|John Doe|45
P002|Jane Smith|32
`);

// Access tables
const patients = doc.tables.get('PATIENTS');
console.log(patients?.rows);
// [{ id: 'P001', name: 'John Doe', age: 45 }, ...]

// Create new document
const newDoc = createDocument('dtWEB', 'pAPI');
addTable(newDoc, 'USERS', { id: 's', name: 's', active: 'b' }, [
  { id: 'U001', name: 'Alice', active: true },
  { id: 'U002', name: 'Bob', active: false },
]);

// Write to DTL string
const dtlString = write(newDoc);

React Integration

import { useDTL, useDTLTable, DTLProvider } from 'dtl-parser/react';

// Hook for parsing DTL
function MyComponent() {
  const { doc, parse, error, loading, getRows } = useDTL();
  
  useEffect(() => {
    parse(dtlContent);
  }, []);
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  const users = getRows('USERS');
  
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Fetch DTL from URL

import { useDTLFetch } from 'dtl-parser/react';

function DataComponent() {
  const { doc, loading, error, refetch } = useDTLFetch({
    url: 'https://api.example.com/data.dtl',
    refreshInterval: 30000, // Refresh every 30s
  });
  
  if (loading) return <div>Loading...</div>;
  
  return (
    <div>
      <button onClick={refetch}>Refresh</button>
      {/* ... */}
    </div>
  );
}

Table Hook

import { useDTLTable } from 'dtl-parser/react';

interface User {
  id: string;
  name: string;
  active: boolean;
}

function UsersTable({ doc }) {
  const { rows, count, find, filter } = useDTLTable<User>({
    doc,
    tableName: 'USERS',
  });
  
  const activeUsers = filter(u => u.active);
  const admin = find(u => u.id === 'admin');
  
  return (
    <div>
      <p>Total: {count}, Active: {activeUsers.length}</p>
      {/* ... */}
    </div>
  );
}

Format Converters

import { fromJSON, toJSON, fromCSV, toCSV, fromXML, toXML } from 'dtl-parser/converters';

// JSON → DTL
const doc = fromJSON({
  users: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
  ],
});

// DTL → JSON
const jsonStr = toJSON(doc);

// CSV → DTL
const csvDoc = fromCSV(`id,name,score
1,Alice,95
2,Bob,87`, { tableName: 'STUDENTS' });

// DTL → CSV
const csvStr = toCSV(doc, 'USERS');

// XML → DTL
const xmlDoc = fromXML('<users><user id="1">Alice</user></users>');

// DTL → XML
const xmlStr = toXML(doc);

Auto-detect Format

import { convertToDTL, convertFromDTL } from 'dtl-parser/converters';

// Auto-detect and convert
const doc1 = convertToDTL('{"data": [1,2,3]}');        // Detects JSON
const doc2 = convertToDTL('id,name\n1,Alice');         // Detects CSV
const doc3 = convertToDTL('<data>...</data>');         // Detects XML
const doc4 = convertToDTL('@dtlv1.0^dtWEB^...');       // Detects DTL

// Convert DTL to any format
const json = convertFromDTL(doc, 'json');
const csv = convertFromDTL(doc, 'csv');
const xml = convertFromDTL(doc, 'xml');

API Reference

Core Functions

| Function | Description | |----------|-------------| | parse(content) | Parse DTL string to document | | write(doc) | Write document to DTL string | | createDocument(domain, profile) | Create new empty document | | addTable(doc, name, schema, rows) | Add table to document | | getTable(doc, name) | Get table by name | | getRows(doc, tableName) | Get table rows as array | | getConfig(doc, key) | Get config value |

Types

interface DTLDocument {
  header: DTLHeader;
  security: DTLSecurityHeader;
  tables: Map<string, DTLTable>;
  raw: string;
}

interface DTLTable {
  name: string;
  schema: Record<string, string>;
  fieldOrder: string[];
  rows: Record<string, any>[];
  rowCount: number;
  securityMode: string;
  web3Mode: string;
}

interface DTLHeader {
  version: string;
  domain: string;
  profile: string;
  compression: string;
  security: string;
  web3: string;
  checksum: string;
}

DTL Types

| Type | JavaScript | Description | |------|------------|-------------| | s | string | String | | i | number | Integer | | f | number | Float | | b | boolean | Boolean (0/1) | | D | Date | Date | | T | Date | Timestamp | | j | object | JSON | | a(s) | string[] | Array |

DTL Format

@dtlv1.0^{domain}^{profile}^{compression}^{security}^{web3}^{checksum}
@sec^{hash}^{wallet}^{signature}^{chainId}

TABLE_NAME|field:type,field:type|rowcount|S|W|C
value1|value2|value3
value1|value2|value3

Example

@dtlv1.0^dtHC^pMedical^c1^s0^w0^abc123
@sec^hash123^0x0^none^0

PATIENTS|id:s,name:s,dob:D,active:b|3|S0|W0|C1
P001|John Doe|1980-05-15|1
P002|Jane Smith|1992-08-22|1
P003|Bob Wilson|1975-12-03|0

VITALS|patient_id:s,bp:s,hr:i,temp:f|2|S0|W0|C1
P001|120/80|72|98.6
P002|118/76|68|98.2

Browser Support

Works in all modern browsers and Node.js 16+.

| Environment | Support | |-------------|---------| | Chrome | ✅ 80+ | | Firefox | ✅ 75+ | | Safari | ✅ 14+ | | Edge | ✅ 80+ | | Node.js | ✅ 16+ |

Related Packages

| Package | Language | Install | |---------|----------|---------| | dtl-parser | Python | pip install dtl-parser | | dtl-parser | JavaScript | npm install dtl-parser |

License

MIT © Padam Sundar Kafle