Data Advanced Notation (DAN)

npm: @marcuwynu23/danjs (danjs)

A human-readable, structured data format that combines the best features of JSON, YAML, CSV, and TOON.

Features • Quick Start • Documentation • Examples

Why DAN?

DAN (Data Advanced Notation) is designed for developers who want:

• Human-readable syntax with minimal punctuation
• Native table support for structured data
• Comments anywhere (# or //)
• Type inference - no explicit type declarations needed
• Fast parsing with single-pass algorithm
• Readable syntax that is easy to read and write

Perfect for configuration files, datasets, structured data, and any scenario where JSON/YAML/CSV fall short.

Quick Start

Installation

npm install @marcuwynu23/danjs

Basic Usage

import { decode, encode } from "@marcuwynu23/danjs";

// Parse DAN text to JavaScript object
const danText = `
name: John
age: 30
active: true
tags: [developer, javascript]
`;

const obj = decode(danText);
console.log(obj);
// { name: 'John', age: 30, active: true, tags: ['developer', 'javascript'] }

// Encode JavaScript object to DAN format
const data = {
  user: {
    name: "Jane",
    email: "[email protected]",
  },
  roles: ["admin", "user"],
};

const danOutput = encode(data);
console.log(danOutput);
// user {
//   name: "Jane"
//   email: "[email protected]"
// }
// roles: [admin, user]

Contents

• Features
• TypeScript Support
• API Reference
• Syntax Guide
• Examples
• Comparison with Other Formats
• Use Cases
• Documentation
• Contributing

Features

| Feature | Description | | --------------------- | ------------------------------------------------ | | Human-readable | Minimal syntax, easy for humans to understand | | Nested blocks | Organize data hierarchically with {} | | Arrays | Simple list syntax with [] | | Native tables | Built-in table support with column headers | | Comments | Inline and block comments using # or // | | Type inference | Automatically detects numbers, booleans, strings | | Fast parsing | Optimized single-pass parser for performance | | Buffer support | Parse directly from Node.js Buffers | | TypeScript | Full type definitions included |

TypeScript Support

This library includes full TypeScript support with comprehensive type definitions.

TypeScript Example

import {
  decode,
  encode,
  type DanObject,
  type DanTableRow,
} from "@marcuwynu23/danjs";

// Decode with type inference
const obj: DanObject = decode(`
name: John
age: 30
active: true
`);

// Type-safe access
const name: string = obj.name as string;
const age: number = obj.age as number;

// Encode with type safety
interface Config {
  user: {
    name: string;
    email: string;
  };
  roles: string[];
}

const config: Config = {
  user: { name: "Jane", email: "[email protected]" },
  roles: ["admin", "user"],
};

const dan: string = encode(config as DanObject);

Available Types

• DanObject - Represents a parsed DAN object
• DanValue - Union type for all possible DAN values
• DanTableRow - Represents a row in a DAN table

API Reference

decode(text: string | Buffer): DanObject

Parses a DAN format string or Buffer and returns a JavaScript object.

Parameters:

• text (string | Buffer): The DAN format text to parse. Can be a string or a Node.js Buffer (e.g., from fs.readFileSync)

Returns:

• DanObject: The parsed JavaScript object

Example:

// With string
const obj = decode("name: John\nage: 30");
// { name: 'John', age: 30 }

// With Buffer (from fs.readFileSync)
import fs from "fs";
const buffer = fs.readFileSync("data.dan");
const obj = decode(buffer); // Automatically converts Buffer to string

// Empty file handling (returns empty object, no error)
const emptyBuffer = fs.readFileSync("empty.dan");
const emptyObj = decode(emptyBuffer); // Returns {} for empty files
// {}

TypeScript:

const obj: DanObject = decode("name: John\nage: 30");

// Or with Buffer
import fs from "fs";
const buffer = fs.readFileSync("data.dan");
const obj: DanObject = decode(buffer);

encode(obj: DanObject, indent?: number): string

Encodes a JavaScript object to DAN format string.

Parameters:

• obj (DanObject): The JavaScript object to encode
• indent (number, optional): Starting indentation level (default: 0)

Returns:

• string: The DAN format string

Example:

const dan = encode({ name: "John", age: 30 });
// name: "John"
// age: 30

TypeScript:

const dan: string = encode({ name: "John", age: 30 } as DanObject);

Syntax Guide

Blocks

Organize data hierarchically with nested blocks:

context {
  key: value
  nestedBlock {
    key: value
  }
}

Arrays

Store lists of values:

friends: [ana, luis, sam]
numbers: [1, 2, 3, 4, 5]
mixed: [hello, 42, true, "world"]

Tables

Native table support for structured tabular data:

hikes: table(id, name, distanceKm) [
  1, "Blue Lake Trail", 7.5
  2, "Ridge Overlook", 9.2
]

Comments

Add documentation anywhere:

# This is a block comment
name: John  # Inline comment
age: 30     // Alternative comment style

Examples

Complete Example

# Context for the hiking trip
context {
  task: "Our favorite hikes together"  # main task description
  location: Boulder
  season: spring_2025

  // forecast for the week
  weatherForecast {
    monday: sunny
    tuesday: cloudy
    wednesday: rainy
    thursday: sunny
  }
}

friends: [ana, luis, sam, julia, mike]  # list of friends

# Hike details table
hikes: table(id, name, distanceKm, elevationGain, companion, wasSunny, difficulty) [
  1, "Blue Lake Trail", 7.5, 320, ana, true, medium
  2, "Ridge Overlook", 9.2, 540, luis, false, hard
  3, "Wildflower Loop", 5.1, 180, sam, true, easy
]

# Animal companions
animals: table(type, name, age, vaccinated) [
  dog, Putcholo, 5, true
  cat, Sebastian, 3, false
  parrot, Polly, 2, true
  rabbit, Fluffy, 1, false
]

games: [chess, "board games", puzzles, "escape room", sudoku]  // fun activities

Configuration File Example

# Application configuration
app {
  name: "My Application"
  version: 1.0.0
  environment: production

  # Server settings
  server {
    host: localhost
    port: 3000
    ssl: false
  }

  # Database configuration
  database {
    type: postgresql
    host: db.example.com
    port: 5432
    name: myapp
  }
}

# Feature flags
features {
  authentication: true
  analytics: false
  logging: true
}

# User roles
roles: [admin, user, guest]

# API endpoints
endpoints: table(method, path, handler, auth) [
  GET, "/api/users", getUsers, true
  POST, "/api/users", createUser, true
  GET, "/api/public", getPublic, false
]

Check out more examples in the examples/ directory!

Comparison with Other Formats

DAN combines the best features of multiple data formats. Here's how it compares:

Feature Comparison

| Feature | DAN | JSON | YAML | TOML | CSV | XML | INI | | ------------------- | --------------- | ---- | ------ | ------ | --- | ------------- | -------------- | | Comments | Yes (# and //) | No | Yes (#) | Yes (#) | No | Yes (<!-- -->) | Yes (# and ;) | | Type Inference | Yes | No | Yes | Yes | No | No | No | | Nested Objects | Yes | Yes | Yes | Yes | No | Yes | No | | Arrays | Yes | Yes | Yes | Yes | No | Yes | No | | Tables | Yes (native) | No | No | No | Yes | No | No | | Minimal Syntax | Yes | No | Partial | Partial | Yes | No | Yes | | Human Readable | Yes | Partial | Yes | Yes | Partial | No | Yes | | Quotes Optional | Yes | No | Yes | Yes | No | No | Yes | | Trailing Commas | Yes | No | Yes | Yes | No | N/A | N/A |

Side-by-Side Examples

The same data structure represented in different formats:

# User configuration
user {
  name: John
  age: 30
  active: true
  tags: [developer, javascript, nodejs]
}

# User roles table
roles: table(id, name, permissions) [
  1, admin, [read, write, delete]
  2, user, [read]
  3, guest, [read]
]

{
  "user": {
    "name": "John",
    "age": 30,
    "active": true,
    "tags": ["developer", "javascript", "nodejs"]
  },
  "roles": [
    { "id": 1, "name": "admin", "permissions": ["read", "write", "delete"] },
    { "id": 2, "name": "user", "permissions": ["read"] },
    { "id": 3, "name": "guest", "permissions": ["read"] }
  ]
}

Issues:

• No comments
• Requires quotes for all strings
• More verbose syntax
• Tables require verbose object arrays

# User configuration
user:
  name: John
  age: 30
  active: true
  tags:
    - developer
    - javascript
    - nodejs

# User roles table
roles:
  - id: 1
    name: admin
    permissions:
      - read
      - write
      - delete
  - id: 2
    name: user
    permissions:
      - read
  - id: 3
    name: guest
    permissions:
      - read

Issues:

• Indentation-sensitive (can be error-prone)
• Tables require verbose nested structures
• More verbose for tabular data
• Complex syntax for simple values

Why Choose DAN?

Choose DAN when you need:

• Tabular data with native table support
• Comments for documentation
• Minimal, readable syntax
• Type inference without explicit typing
• Mix of structured and tabular data
• Fast parsing performance

Consider alternatives when:

• You need maximum compatibility (use JSON)
• You need strict schema validation (use JSON Schema + JSON)
• You need industry-standard format (use YAML/TOML)
• You only need simple key-value pairs (use INI)

Use Cases

DAN is perfect for:

• Configuration files for applications or services
• Human-readable datasets for analytics
• Structured experiment results
• Data serialization with human readability
• Documentation with embedded data
• Tabular data representation

File Extension

DAN files use the .dan extension:

filename.dan

Example: hiking_trip.dan, config.dan, data.dan

Documentation

• FEATURES.md - Comprehensive feature documentation
• CONTRIBUTING.md - Guidelines for contributing
• CHANGELOG.md - Version history and changes
• SECURITY.md - How to report vulnerabilities responsibly
• Examples - Code examples and use cases

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Code of Conduct
• Development setup
• Pull request process
• Coding standards

See our Security Policy for reporting vulnerabilities. You can also support maintenance via PayPal (see the Sponsor / Funding button on the repository).

License

This project is licensed under the ISC License - see the LICENSE file for details.

Acknowledgments

DAN is inspired by the best features of JSON, YAML, CSV, and TOON, combining them into a single, powerful format.

Made for developers who love clean, readable data formats

Report Bug • Request Feature • Documentation