Open Datascript (HDS) by Pkg.lat

Open Datascript (HDS) is a streamlined data-authoring language designed by Pkg.lat. It acts as a human-centric abstraction layer over JSON, allowing for structured data that is easy for people to write while remaining perfectly identifiable by machines.

🚀 Core Concepts

The Parser

HDS uses a brace-delimited structure. When braces are opened, a root is established.

{
    // This data lives in the root
    thisDataLivesInRoot
}

Object System

HDS supports nested object structures for organizing complex data.

{
    object = {
        data = {Hello}
    }
}

Complex Nesting

You can nest objects indefinitely to represent sophisticated data trees.

{
    object = {
        data = {Hello}
        data2 = {
            object = {
                data = {Hello}
            }
        }
    }
}

🛠 Helpers

Helpers are optional features that allow for dynamic data injection and caching. They must be manually enabled to avoid conflicts with static data structures.

Basic Helpers

Use the @helpers block to define fields and behaviors like caching.

{
   @helpers {
        field 1
        cache enabled
    }
    object = {
        data = {@field(1)}
    }
}

Verbose Helpers (Scoped Caching)

You can define specific data blocks within helpers to ensure only specific variables are cached or retrieved from external fields.

{
   @helpers {
        @data-1 {
            field 1
            cache enabled
        }
    }
    object = {
        data = {@data-1}
    }
}

Environment Variables

HDS supports environment-specific data injection via the @env helper.

{
    env = {
        prod = {@env(BUILD_TYPE)}
    }
}

📝 Syntax Features

Comments

The HDS engine ignores lines starting with //, allowing for documentation within your data files.

{
    // This is a comment and will be omitted by the HDS engine
    key = {value}
}

🔨 The Compiler

HDS is designed for humans, but its output is for machines. The compiler natively converts .hds files into .json.

Architecture

The compiler is built for high performance and portability, available as:

• Native Binaries: For CLI-based workflows.
• WASM (WebAssembly): For integration into web applications and browser environments.

Usage Examples

Native CLI

Pass fields and output paths directly via the terminal:

hds compile ./test.hds \
  -o ./test.json \
  --field 1=hello \
  --field 2=world

WASM API

Integrate HDS compilation directly into your JavaScript projects:

const output = hds.compile(source, {
  fields: { 1: "hello" },
  set: { "cache.enabled": true }
});