open-index/open-npm huggingface dataset:
npm package: @nadhi.dev/datascript
Description: 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.
Latest version: 0.1.0

# 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.

```hds
{
    // This data lives in the root
    thisDataLivesInRoot
}

```

### Object System

HDS supports nested object structures for organizing complex data.

```hds
{
    object = {
        data = {Hello}
    }
}

```

### Complex Nesting

You can nest objects indefinitely to represent sophisticated data trees.

```hds
{
    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.

```hds
{
   @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.

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

```

### Environment Variables

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

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

```

---

## 📝 Syntax Features

### Comments

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

```hds
{
    // 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:

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

```

#### WASM API

Integrate HDS compilation directly into your JavaScript projects:

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

```

---