{"id":50664485,"url":"https://github.com/marcuwynu23/danjs","last_synced_at":"2026-06-08T05:02:57.957Z","repository":{"id":328733130,"uuid":"1116502942","full_name":"marcuwynu23/danjs","owner":"marcuwynu23","description":"a human-readable data format for structured configs, datasets, and annotations with tables, arrays, and comments","archived":false,"fork":false,"pushed_at":"2026-04-21T13:53:05.000Z","size":54,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T15:42:25.268Z","etag":null,"topics":["configuration","csv","dan","data-format","javascript","json","notation","parser","structured-data","toon","typescript","xml"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@marcuwynu23/danjs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcuwynu23.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://paypal.me/wynumarcu23"]}},"created_at":"2025-12-15T01:04:10.000Z","updated_at":"2026-04-21T14:31:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcuwynu23/danjs","commit_stats":null,"previous_names":["marcuwynu23/dan"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/marcuwynu23/danjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fdanjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fdanjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fdanjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fdanjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcuwynu23","download_url":"https://codeload.github.com/marcuwynu23/danjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fdanjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34048681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","csv","dan","data-format","javascript","json","notation","parser","structured-data","toon","typescript","xml"],"created_at":"2026-06-08T05:02:53.654Z","updated_at":"2026-06-08T05:02:57.952Z","avatar_url":"https://github.com/marcuwynu23.png","language":"JavaScript","funding_links":["https://paypal.me/wynumarcu23"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Data Advanced Notation (DAN)\n\n**npm:** [`@marcuwynu23/danjs`](https://www.npmjs.com/package/@marcuwynu23/danjs) (danjs)\n\n**A human-readable, structured data format** that combines the best features of JSON, YAML, CSV, and TOON.\n\n[![npm version](https://img.shields.io/npm/v/@marcuwynu23/danjs?style=flat-square)](https://www.npmjs.com/package/@marcuwynu23/danjs)\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://opensource.org/licenses/ISC)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-ESM-green?style=flat-square)](https://nodejs.org/)\n\n[Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Examples](#examples)\n\n\u003c/div\u003e\n\n---\n\n## Why DAN?\n\n**DAN** (Data Advanced Notation) is designed for developers who want:\n\n- **Human-readable** syntax with minimal punctuation\n- **Native table support** for structured data\n- **Comments** anywhere (`#` or `//`)\n- **Type inference** - no explicit type declarations needed\n- **Fast parsing** with single-pass algorithm\n- **Readable syntax** that is easy to read and write\n\nPerfect for **configuration files**, **datasets**, **structured data**, and any scenario where JSON/YAML/CSV fall short.\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install @marcuwynu23/danjs\n```\n\n### Basic Usage\n\n```javascript\nimport { decode, encode } from \"@marcuwynu23/danjs\";\n\n// Parse DAN text to JavaScript object\nconst danText = `\nname: John\nage: 30\nactive: true\ntags: [developer, javascript]\n`;\n\nconst obj = decode(danText);\nconsole.log(obj);\n// { name: 'John', age: 30, active: true, tags: ['developer', 'javascript'] }\n\n// Encode JavaScript object to DAN format\nconst data = {\n  user: {\n    name: \"Jane\",\n    email: \"jane@example.com\",\n  },\n  roles: [\"admin\", \"user\"],\n};\n\nconst danOutput = encode(data);\nconsole.log(danOutput);\n// user {\n//   name: \"Jane\"\n//   email: \"jane@example.com\"\n// }\n// roles: [admin, user]\n```\n\n---\n\n## Contents\n\n- [Features](#features)\n- [TypeScript Support](#typescript-support)\n- [API Reference](#api-reference)\n- [Syntax Guide](#syntax-guide)\n- [Examples](#examples)\n- [Comparison with Other Formats](#comparison-with-other-formats)\n- [Use Cases](#use-cases)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n---\n\n## Features\n\n| Feature               | Description                                      |\n| --------------------- | ------------------------------------------------ |\n| **Human-readable**    | Minimal syntax, easy for humans to understand    |\n| **Nested blocks**     | Organize data hierarchically with `{}`           |\n| **Arrays**            | Simple list syntax with `[]`                     |\n| **Native tables**     | Built-in table support with column headers       |\n| **Comments**          | Inline and block comments using `#` or `//`      |\n| **Type inference**    | Automatically detects numbers, booleans, strings |\n| **Fast parsing**      | Optimized single-pass parser for performance     |\n| **Buffer support**    | Parse directly from Node.js Buffers              |\n| **TypeScript**        | Full type definitions included                   |\n\n---\n\n## TypeScript Support\n\nThis library includes **full TypeScript support** with comprehensive type definitions.\n\n### TypeScript Example\n\n```typescript\nimport {\n  decode,\n  encode,\n  type DanObject,\n  type DanTableRow,\n} from \"@marcuwynu23/danjs\";\n\n// Decode with type inference\nconst obj: DanObject = decode(`\nname: John\nage: 30\nactive: true\n`);\n\n// Type-safe access\nconst name: string = obj.name as string;\nconst age: number = obj.age as number;\n\n// Encode with type safety\ninterface Config {\n  user: {\n    name: string;\n    email: string;\n  };\n  roles: string[];\n}\n\nconst config: Config = {\n  user: { name: \"Jane\", email: \"jane@example.com\" },\n  roles: [\"admin\", \"user\"],\n};\n\nconst dan: string = encode(config as DanObject);\n```\n\n### Available Types\n\n- `DanObject` - Represents a parsed DAN object\n- `DanValue` - Union type for all possible DAN values\n- `DanTableRow` - Represents a row in a DAN table\n\n---\n\n## API Reference\n\n### `decode(text: string | Buffer): DanObject`\n\nParses a DAN format string or Buffer and returns a JavaScript object.\n\n**Parameters:**\n\n- `text` (string | Buffer): The DAN format text to parse. Can be a string or a Node.js Buffer (e.g., from `fs.readFileSync`)\n\n**Returns:**\n\n- `DanObject`: The parsed JavaScript object\n\n**Example:**\n\n```javascript\n// With string\nconst obj = decode(\"name: John\\nage: 30\");\n// { name: 'John', age: 30 }\n\n// With Buffer (from fs.readFileSync)\nimport fs from \"fs\";\nconst buffer = fs.readFileSync(\"data.dan\");\nconst obj = decode(buffer); // Automatically converts Buffer to string\n\n// Empty file handling (returns empty object, no error)\nconst emptyBuffer = fs.readFileSync(\"empty.dan\");\nconst emptyObj = decode(emptyBuffer); // Returns {} for empty files\n// {}\n```\n\n**TypeScript:**\n\n```typescript\nconst obj: DanObject = decode(\"name: John\\nage: 30\");\n\n// Or with Buffer\nimport fs from \"fs\";\nconst buffer = fs.readFileSync(\"data.dan\");\nconst obj: DanObject = decode(buffer);\n```\n\n### `encode(obj: DanObject, indent?: number): string`\n\nEncodes a JavaScript object to DAN format string.\n\n**Parameters:**\n\n- `obj` (DanObject): The JavaScript object to encode\n- `indent` (number, optional): Starting indentation level (default: 0)\n\n**Returns:**\n\n- `string`: The DAN format string\n\n**Example:**\n\n```javascript\nconst dan = encode({ name: \"John\", age: 30 });\n// name: \"John\"\n// age: 30\n```\n\n**TypeScript:**\n\n```typescript\nconst dan: string = encode({ name: \"John\", age: 30 } as DanObject);\n```\n\n---\n\n## Syntax Guide\n\n### Blocks\n\nOrganize data hierarchically with nested blocks:\n\n```dan\ncontext {\n  key: value\n  nestedBlock {\n    key: value\n  }\n}\n```\n\n### Arrays\n\nStore lists of values:\n\n```dan\nfriends: [ana, luis, sam]\nnumbers: [1, 2, 3, 4, 5]\nmixed: [hello, 42, true, \"world\"]\n```\n\n### Tables\n\nNative table support for structured tabular data:\n\n```dan\nhikes: table(id, name, distanceKm) [\n  1, \"Blue Lake Trail\", 7.5\n  2, \"Ridge Overlook\", 9.2\n]\n```\n\n### Comments\n\nAdd documentation anywhere:\n\n```dan\n# This is a block comment\nname: John  # Inline comment\nage: 30     // Alternative comment style\n```\n\n---\n\n## Examples\n\n### Complete Example\n\n```dan\n# Context for the hiking trip\ncontext {\n  task: \"Our favorite hikes together\"  # main task description\n  location: Boulder\n  season: spring_2025\n\n  // forecast for the week\n  weatherForecast {\n    monday: sunny\n    tuesday: cloudy\n    wednesday: rainy\n    thursday: sunny\n  }\n}\n\nfriends: [ana, luis, sam, julia, mike]  # list of friends\n\n# Hike details table\nhikes: table(id, name, distanceKm, elevationGain, companion, wasSunny, difficulty) [\n  1, \"Blue Lake Trail\", 7.5, 320, ana, true, medium\n  2, \"Ridge Overlook\", 9.2, 540, luis, false, hard\n  3, \"Wildflower Loop\", 5.1, 180, sam, true, easy\n]\n\n# Animal companions\nanimals: table(type, name, age, vaccinated) [\n  dog, Putcholo, 5, true\n  cat, Sebastian, 3, false\n  parrot, Polly, 2, true\n  rabbit, Fluffy, 1, false\n]\n\ngames: [chess, \"board games\", puzzles, \"escape room\", sudoku]  // fun activities\n```\n\n### Configuration File Example\n\n```dan\n# Application configuration\napp {\n  name: \"My Application\"\n  version: 1.0.0\n  environment: production\n\n  # Server settings\n  server {\n    host: localhost\n    port: 3000\n    ssl: false\n  }\n\n  # Database configuration\n  database {\n    type: postgresql\n    host: db.example.com\n    port: 5432\n    name: myapp\n  }\n}\n\n# Feature flags\nfeatures {\n  authentication: true\n  analytics: false\n  logging: true\n}\n\n# User roles\nroles: [admin, user, guest]\n\n# API endpoints\nendpoints: table(method, path, handler, auth) [\n  GET, \"/api/users\", getUsers, true\n  POST, \"/api/users\", createUser, true\n  GET, \"/api/public\", getPublic, false\n]\n```\n\nCheck out more examples in the [`examples/`](./examples/) directory!\n\n---\n\n## Comparison with Other Formats\n\nDAN combines the best features of multiple data formats. Here's how it compares:\n\n### Feature Comparison\n\n| Feature             | DAN             | JSON | YAML   | TOML   | CSV | XML           | INI            |\n| ------------------- | --------------- | ---- | ------ | ------ | --- | ------------- | -------------- |\n| **Comments**        | Yes (`#` and `//`) | No   | Yes (`#`) | Yes (`#`) | No  | Yes (`\u003c!-- --\u003e`) | Yes (`#` and `;`) |\n| **Type Inference**  | Yes                | No   | Yes       | Yes       | No  | No               | No                |\n| **Nested Objects**  | Yes                | Yes  | Yes       | Yes       | No  | Yes              | No                |\n| **Arrays**          | Yes                | Yes  | Yes       | Yes       | No  | Yes              | No                |\n| **Tables**          | Yes (native)       | No   | No        | No        | Yes | No               | No                |\n| **Minimal Syntax**  | Yes                | No   | Partial   | Partial   | Yes | No               | Yes               |\n| **Human Readable**  | Yes                | Partial | Yes    | Yes       | Partial | No          | Yes               |\n| **Quotes Optional** | Yes                | No   | Yes       | Yes       | No  | No               | Yes               |\n| **Trailing Commas** | Yes                | No   | Yes       | Yes       | No  | N/A              | N/A               |\n\n### Side-by-Side Examples\n\nThe same data structure represented in different formats:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDAN\u003c/b\u003e - Clean and readable\u003c/summary\u003e\n\n```dan\n# User configuration\nuser {\n  name: John\n  age: 30\n  active: true\n  tags: [developer, javascript, nodejs]\n}\n\n# User roles table\nroles: table(id, name, permissions) [\n  1, admin, [read, write, delete]\n  2, user, [read]\n  3, guest, [read]\n]\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eJSON\u003c/b\u003e - Verbose, no comments\u003c/summary\u003e\n\n```json\n{\n  \"user\": {\n    \"name\": \"John\",\n    \"age\": 30,\n    \"active\": true,\n    \"tags\": [\"developer\", \"javascript\", \"nodejs\"]\n  },\n  \"roles\": [\n    { \"id\": 1, \"name\": \"admin\", \"permissions\": [\"read\", \"write\", \"delete\"] },\n    { \"id\": 2, \"name\": \"user\", \"permissions\": [\"read\"] },\n    { \"id\": 3, \"name\": \"guest\", \"permissions\": [\"read\"] }\n  ]\n}\n```\n\n**Issues:**\n\n- No comments\n- Requires quotes for all strings\n- More verbose syntax\n- Tables require verbose object arrays\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eYAML\u003c/b\u003e - Indentation-sensitive\u003c/summary\u003e\n\n```yaml\n# User configuration\nuser:\n  name: John\n  age: 30\n  active: true\n  tags:\n    - developer\n    - javascript\n    - nodejs\n\n# User roles table\nroles:\n  - id: 1\n    name: admin\n    permissions:\n      - read\n      - write\n      - delete\n  - id: 2\n    name: user\n    permissions:\n      - read\n  - id: 3\n    name: guest\n    permissions:\n      - read\n```\n\n**Issues:**\n\n- Indentation-sensitive (can be error-prone)\n- Tables require verbose nested structures\n- More verbose for tabular data\n- Complex syntax for simple values\n\n\u003c/details\u003e\n\n### Why Choose DAN?\n\n**Choose DAN when you need:**\n\n- Tabular data with native table support\n- Comments for documentation\n- Minimal, readable syntax\n- Type inference without explicit typing\n- Mix of structured and tabular data\n- Fast parsing performance\n\n**Consider alternatives when:**\n\n- You need maximum compatibility (use JSON)\n- You need strict schema validation (use JSON Schema + JSON)\n- You need industry-standard format (use YAML/TOML)\n- You only need simple key-value pairs (use INI)\n\n---\n\n## Use Cases\n\nDAN is perfect for:\n\n- **Configuration files** for applications or services\n- **Human-readable datasets** for analytics\n- **Structured experiment results**\n- **Data serialization** with human readability\n- **Documentation** with embedded data\n- **Tabular data representation**\n\n---\n\n## File Extension\n\nDAN files use the `.dan` extension:\n\n```\nfilename.dan\n```\n\nExample: `hiking_trip.dan`, `config.dan`, `data.dan`\n\n---\n\n## Documentation\n\n- **[FEATURES.md](./FEATURES.md)** - Comprehensive feature documentation\n- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Guidelines for contributing\n- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and changes\n- **[SECURITY.md](./SECURITY.md)** - How to report vulnerabilities responsibly\n- **[Examples](./examples/)** - Code examples and use cases\n\n---\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on:\n\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- Development setup\n- Pull request process\n- Coding standards\n\nSee our [Security Policy](./SECURITY.md) for reporting vulnerabilities. You can also support maintenance via [PayPal](https://paypal.me/wynumarcu23) (see the **Sponsor** / Funding button on the repository).\n\n---\n\n## License\n\nThis project is licensed under the **ISC License** - see the [LICENSE](./LICENSE) file for details.\n\n---\n\n## Acknowledgments\n\nDAN is inspired by the best features of JSON, YAML, CSV, and TOON, combining them into a single, powerful format.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made for developers who love clean, readable data formats**\n\n[Report Bug](https://github.com/marcuwynu23/danjs/issues) • [Request Feature](https://github.com/marcuwynu23/danjs/issues) • [Documentation](./FEATURES.md)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fdanjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcuwynu23%2Fdanjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fdanjs/lists"}