yamlstar 0.0.1 → 0.1.2

package/Makefile

@@ -1,21 +1,24 @@
-SHELL := bash
+include ../common/init.mk
+include $M/node.mk
+include $(COMMON)/common.mk
+include $(COMMON)/binding.mk
 
-COFFEE := $(shell find src -type f -name '*.coffee')
-JS := $(COFFEE:%.coffee=%.js)
-JS := $(JS:src/%=lib/%)
+NODE-MODULES := node_modules
 
-default:
-	@printf '%s\n' $(JS)
+MAKES-CLEAN := \
+  .npmrc \
+  package-lock.json \
 
-build: $(JS)
+MAKES-REALCLEAN := \
+  $(NODE-MODULES) \
 
-lib/%.js: src/%.coffee
-	@mkdir -p $(dir $@)
-	coffee -c -p $< > $@
 
-publish: build
-	npm $@
+test: $(NODE-MODULES) $(LIBYAMLSTAR-SO)
+	node test/test.js
 
-clean:
-	rm -f package*
-	rm -fr node_modules
+build: $(LIBYAMLSTAR-SO)
+
+node_modules: package.json $(NODE)
+	npm install
+
+release-deps:: $(NODE)

package/ReadMe.md

@@ -0,0 +1,326 @@
+# YAMLStar Node.js Bindings
+
+Node.js bindings for YAMLStar - a pure YAML 1.2 loader implemented in Clojure.
+
+## Features
+
+- **YAML 1.2 Spec Compliance**: 100% compliant with YAML 1.2 core schema
+- **Pure Implementation**: No dependencies on js-yaml or other external parsers
+- **Fast Native Performance**: Uses GraalVM native-image shared library
+- **Simple API**: Load YAML documents with a single method call
+- **Multi-Document Support**: Load multiple YAML documents from a single string
+
+## Installation
+
+### Prerequisites
+
+First, build and install the shared library:
+
+```bash
+cd ../libyamlstar
+make native
+sudo make install PREFIX=/usr/local
+```
+
+Or install to user-local directory:
+
+```bash
+cd ../libyamlstar
+make native
+make install PREFIX=~/.local
+```
+
+### Install Node.js Package
+
+```bash
+npm install @yaml/yamlstar
+```
+
+For development:
+
+```bash
+npm install
+```
+
+## Quick Start
+
+```javascript
+const YAMLStar = require('@yaml/yamlstar');
+
+// Create a YAMLStar instance
+const ys = new YAMLStar();
+
+// Load a simple YAML string
+const data = ys.load('key: value');
+console.log(data);  // { key: 'value' }
+
+// Clean up when done
+ys.close();
+```
+
+## Usage Examples
+
+### Basic Types
+
+```javascript
+const YAMLStar = require('@yaml/yamlstar');
+const ys = new YAMLStar();
+
+// Strings
+ys.load('hello');  // 'hello'
+
+// Integers
+ys.load('42');  // 42
+
+// Floats
+ys.load('3.14');  // 3.14
+
+// Booleans
+ys.load('true');   // true
+ys.load('false');  // false
+
+// Null
+ys.load('null');  // null
+```
+
+### Collections
+
+```javascript
+// Mappings (objects)
+const data = ys.load(`
+name: Alice
+age: 30
+city: Seattle
+`);
+// { name: 'Alice', age: 30, city: 'Seattle' }
+
+// Sequences (arrays)
+const data = ys.load(`
+- apple
+- banana
+- orange
+`);
+// ['apple', 'banana', 'orange']
+
+// Flow style
+const data = ys.load('[a, b, c]');
+// ['a', 'b', 'c']
+```
+
+### Nested Structures
+
+```javascript
+const data = ys.load(`
+person:
+  name: Alice
+  age: 30
+  hobbies:
+    - reading
+    - coding
+    - hiking
+`);
+// {
+//   person: {
+//     name: 'Alice',
+//     age: 30,
+//     hobbies: ['reading', 'coding', 'hiking']
+//   }
+// }
+```
+
+### Multi-Document YAML
+
+```javascript
+// Load all documents from a multi-document YAML string
+const docs = ys.loadAll(`---
+name: Document 1
+---
+name: Document 2
+---
+name: Document 3
+`);
+// [
+//   { name: 'Document 1' },
+//   { name: 'Document 2' },
+//   { name: 'Document 3' }
+// ]
+```
+
+### Type Coercion
+
+YAMLStar follows YAML 1.2 core schema type inference:
+
+```javascript
+const data = ys.load(`
+string: hello
+integer: 42
+float: 3.14
+bool_true: true
+bool_false: false
+null_value: null
+`);
+// {
+//   string: 'hello',
+//   integer: 42,
+//   float: 3.14,
+//   bool_true: true,
+//   bool_false: false,
+//   null_value: null
+// }
+```
+
+### Error Handling
+
+```javascript
+try {
+  const data = ys.load('invalid: yaml: syntax');
+} catch (error) {
+  console.error('Error loading YAML:', error.message);
+}
+```
+
+### Version Information
+
+```javascript
+// Get YAMLStar version
+const version = ys.version();
+console.log(`YAMLStar version: ${version}`);
+```
+
+### Resource Cleanup
+
+```javascript
+const ys = new YAMLStar();
+
+// ... use ys ...
+
+// Clean up GraalVM isolate when done
+ys.close();
+```
+
+## API Reference
+
+### `YAMLStar` Class
+
+#### `new YAMLStar()`
+Create a new YAMLStar instance. Each instance maintains its own GraalVM isolate.
+
+```javascript
+const ys = new YAMLStar();
+```
+
+#### `load(yamlInput)`
+Load a single YAML document.
+
+**Parameters:**
+- `yamlInput` (string): String containing YAML content
+
+**Returns:**
+- JavaScript value representing the YAML document (object, array, string, number, boolean, or null)
+
+**Throws:**
+- `Error` if the YAML is malformed
+
+**Example:**
+```javascript
+const data = ys.load('key: value');
+```
+
+#### `loadAll(yamlInput)`
+Load all YAML documents from a multi-document string.
+
+**Parameters:**
+- `yamlInput` (string): String containing one or more YAML documents
+
+**Returns:**
+- Array of JavaScript values, one per YAML document
+
+**Throws:**
+- `Error` if the YAML is malformed
+
+**Example:**
+```javascript
+const docs = ys.loadAll('---\ndoc1\n---\ndoc2');
+```
+
+#### `version()`
+Get the YAMLStar version string.
+
+**Returns:**
+- string: Version string
+
+**Example:**
+```javascript
+const version = ys.version();
+```
+
+#### `close()`
+Tear down the GraalVM isolate and free resources. Should be called when done using the instance.
+
+**Example:**
+```javascript
+ys.close();
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Or directly with node
+node test/test.js
+```
+
+### Building libyamlstar
+
+If you need to rebuild the shared library:
+
+```bash
+cd ../libyamlstar
+make clean
+make native
+```
+
+## Requirements
+
+- **Node.js**: 18.0.0 or higher
+- **libyamlstar**: Shared library (installed separately)
+- **System**: Linux or macOS
+- **Dependencies**: `@makeomatic/ffi-napi`, `ref-napi`
+
+## Library Search Path
+
+The module searches for `libyamlstar.so` (or `.dylib` on macOS) in:
+
+1. Development path (relative to module: `../../libyamlstar/lib/`)
+2. Directories in `LD_LIBRARY_PATH` environment variable
+3. `/usr/local/lib` (default install location)
+4. `~/.local/lib` (user-local install location)
+
+## Comparison to js-yaml
+
+| Feature | YAMLStar | js-yaml |
+|---------|----------|---------|
+| YAML Version | 1.2 | 1.2 |
+| Implementation | Pure Clojure | JavaScript |
+| Type Inference | YAML 1.2 core schema | YAML 1.2 + custom |
+| Native Performance | Yes (GraalVM) | No |
+| Dependencies | libyamlstar.so | None |
+
+## License
+
+MIT License - See [License](License) file
+
+## Credits
+
+Created by Ingy döt Net, inventor of YAML.
+
+YAMLStar is built on the YAML Reference Parser (pure Clojure implementation).
+
+## Links
+
+- **GitHub**: https://github.com/yaml/yamlstar
+- **YAML Specification**: https://yaml.org/spec/1.2/spec.html

package/lib/yamlstar/index.js

@@ -0,0 +1,125 @@
+const yamlstarVersion = '0.1.2';
+
+const ffi = require('@makeomatic/ffi-napi');
+const ref = require('ref-napi');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function defineForeignFunctionInterface() {
+  let libPath = findLibyamlstarPath();
+
+  return ffi.Library(libPath, {
+    'graal_create_isolate': ['int', ['pointer', 'pointer', 'pointer']],
+    'graal_tear_down_isolate': ['int', ['pointer']],
+    'yamlstar_load': ['string', ['pointer', 'string']],
+    'yamlstar_load_all': ['string', ['pointer', 'string']],
+    'yamlstar_version': ['string', ['pointer']],
+  });
+}
+
+class YAMLStar {
+  constructor(config = {}) {
+    this.libyamlstar = defineForeignFunctionInterface();
+    this.isolatethread = ref.NULL_POINTER;
+
+    let rc = this.libyamlstar.graal_create_isolate(
+      null,
+      null,
+      this.isolatethread,
+    );
+
+    if (rc !== 0) {
+      throw new Error('Failed to create GraalVM isolate');
+    }
+  }
+
+  load(input) {
+    let dataJson = this.libyamlstar.yamlstar_load(
+      this.isolatethread.deref(),
+      input,
+    );
+
+    let resp = JSON.parse(dataJson);
+
+    if (resp.error) {
+      throw new Error(`libyamlstar: ${resp.error.cause}`);
+    }
+
+    if (!('data' in resp)) {
+      throw new Error("Unexpected response from 'libyamlstar'");
+    }
+
+    return resp.data;
+  }
+
+  loadAll(input) {
+    let dataJson = this.libyamlstar.yamlstar_load_all(
+      this.isolatethread.deref(),
+      input,
+    );
+
+    let resp = JSON.parse(dataJson);
+
+    if (resp.error) {
+      throw new Error(`libyamlstar: ${resp.error.cause}`);
+    }
+
+    if (!('data' in resp)) {
+      throw new Error("Unexpected response from 'libyamlstar'");
+    }
+
+    return resp.data;
+  }
+
+  version() {
+    return this.libyamlstar.yamlstar_version(this.isolatethread.deref());
+  }
+
+  close() {
+    let ret = this.libyamlstar.graal_tear_down_isolate(
+      this.isolatethread.deref(),
+    );
+
+    if (ret !== 0) {
+      throw new Error("Failed to tear down isolate.");
+    }
+  }
+}
+
+// Helper function to find the libyamlstar shared library path
+function findLibyamlstarPath() {
+  let platform = os.platform();
+  let soExtension = platform === 'win32' ? 'dll' : (platform === 'linux' ? 'so' : 'dylib');
+  let libyamlstarName = `libyamlstar.${soExtension}.${yamlstarVersion}`;
+
+  let searchPaths = [];
+
+  // Add relative path for development (from nodejs/lib/yamlstar to libyamlstar/lib)
+  let devPath = path.join(__dirname, '..', '..', '..', 'libyamlstar', 'lib');
+  if (fs.existsSync(devPath)) {
+    searchPaths.push(devPath);
+  }
+
+  // Add LD_LIBRARY_PATH
+  if (process.env.LD_LIBRARY_PATH) {
+    searchPaths.push(...process.env.LD_LIBRARY_PATH.split(':'));
+  }
+
+  // Add system paths
+  searchPaths.push('/usr/local/lib', path.join(os.homedir(), '.local', 'lib'));
+
+  for (let p of searchPaths) {
+    let fullPath = path.join(p, libyamlstarName);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+
+  throw new Error(
+`Shared library file '${libyamlstarName}' not found
+Search paths: ${searchPaths.join(':')}
+Build with: cd libyamlstar && make native`);
+}
+
+module.exports = YAMLStar;

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "yamlstar",
-  "version": "0.0.1",
-  "description": "A cross-language, common API YAML reference framework",
-  "main": "index.js",
+  "version": "0.1.2",
+  "description": "YAML 1.2 loader - Node.js bindings",
+  "main": "lib/yamlstar/index.js",
+  "author": "Ingy döt Net",
+  "license": "MIT",
+  "dependencies": {
+    "@makeomatic/ffi-napi": "^4.2.0",
+    "ref-napi": "^3.0.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "directories": {
-    "lib": "lib"
+    "test": "test"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "make test"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yaml/yamlstar.git"
   },
-  "author": "Ingy döt Net",
-  "license": "MIT",
   "bugs": {
     "url": "https://github.com/yaml/yamlstar/issues"
   },

package/test/test.js

@@ -0,0 +1,146 @@
+const YAMLStar = require('../lib/yamlstar');
+const assert = require('assert');
+
+// Helper function for deep equality check
+function deepEqual(actual, expected, message) {
+  try {
+    assert.deepStrictEqual(actual, expected);
+    console.log(`✓ ${message}`);
+  } catch (e) {
+    console.error(`✗ ${message}`);
+    console.error(`  Expected: ${JSON.stringify(expected)}`);
+    console.error(`  Actual:   ${JSON.stringify(actual)}`);
+    process.exit(1);
+  }
+}
+
+// Create a YAMLStar instance
+const ys = new YAMLStar();
+
+console.log('Running YAMLStar tests...\n');
+
+// Test simple scalar
+deepEqual(ys.load('hello'), 'hello', 'Load simple scalar');
+
+// Test integer
+deepEqual(ys.load('42'), 42, 'Load integer');
+
+// Test float
+deepEqual(ys.load('3.14'), 3.14, 'Load float');
+
+// Test boolean true
+deepEqual(ys.load('true'), true, 'Load boolean true');
+
+// Test boolean false
+deepEqual(ys.load('false'), false, 'Load boolean false');
+
+// Test null
+deepEqual(ys.load('null'), null, 'Load null');
+
+// Test simple mapping
+deepEqual(ys.load('key: value'), {key: 'value'}, 'Load simple mapping');
+
+// Test nested mapping
+deepEqual(
+  ys.load('outer:\n  inner: value'),
+  {outer: {inner: 'value'}},
+  'Load nested mapping'
+);
+
+// Test mapping with multiple keys
+deepEqual(
+  ys.load('key1: value1\nkey2: value2\nkey3: value3'),
+  {key1: 'value1', key2: 'value2', key3: 'value3'},
+  'Load mapping with multiple keys'
+);
+
+// Test simple sequence
+deepEqual(
+  ys.load('- item1\n- item2\n- item3'),
+  ['item1', 'item2', 'item3'],
+  'Load simple sequence'
+);
+
+// Test flow sequence
+deepEqual(ys.load('[a, b, c]'), ['a', 'b', 'c'], 'Load flow sequence');
+
+// Test type coercion
+deepEqual(
+  ys.load('string: hello\ninteger: 42\nfloat: 3.14\nbool_true: true\nbool_false: false\nnull_value: null'),
+  {
+    string: 'hello',
+    integer: 42,
+    float: 3.14,
+    bool_true: true,
+    bool_false: false,
+    null_value: null
+  },
+  'Load with type coercion'
+);
+
+// Test sequence of mappings
+deepEqual(
+  ys.load('- name: Alice\n  age: 30\n- name: Bob\n  age: 25'),
+  [
+    {name: 'Alice', age: 30},
+    {name: 'Bob', age: 25}
+  ],
+  'Load sequence of mappings'
+);
+
+// Test mapping with sequence values
+deepEqual(
+  ys.load('fruits:\n  - apple\n  - banana\ncolors:\n  - red\n  - blue'),
+  {
+    fruits: ['apple', 'banana'],
+    colors: ['red', 'blue']
+  },
+  'Load mapping with sequence values'
+);
+
+// Test loadAll with single document
+deepEqual(ys.loadAll('hello'), ['hello'], 'LoadAll with single document');
+
+// Test loadAll with multiple documents
+deepEqual(
+  ys.loadAll('---\ndoc1\n---\ndoc2\n---\ndoc3'),
+  ['doc1', 'doc2', 'doc3'],
+  'LoadAll with multiple documents'
+);
+
+// Test loadAll with explicit markers
+deepEqual(
+  ys.loadAll('---\na: 1\n...\n---\nb: 2\n...'),
+  [{a: 1}, {b: 2}],
+  'LoadAll with explicit markers'
+);
+
+// Test version
+const version = ys.version();
+assert(typeof version === 'string' && version.length > 0, 'Version returns a string');
+console.log(`✓ Version returns a string: ${version}`);
+
+// Test error handling with malformed YAML
+try {
+  ys.load('key: "unclosed');
+  console.error('✗ Should have thrown error on malformed YAML');
+  process.exit(1);
+} catch (e) {
+  assert(e.message.includes('libyamlstar'), 'Error message includes libyamlstar');
+  console.log('✓ Dies with libyamlstar error on malformed YAML');
+}
+
+// Test empty document
+deepEqual(ys.load(''), null, 'Load empty document');
+
+// Test whitespace only
+deepEqual(ys.load('   \n  \n  '), null, 'Load whitespace only');
+
+// Test quoted strings
+deepEqual(ys.load("'hello world'"), 'hello world', 'Load single-quoted string');
+deepEqual(ys.load('"hello world"'), 'hello world', 'Load double-quoted string');
+
+// Clean up
+ys.close();
+
+console.log('\n✓ All tests passed!');

package/Changes

@@ -1,5 +0,0 @@
----
-version: 0.0.1
-date:    Mon Apr 17 12:19:29 PM PDT 2023
-changes:
-- First release

package/src/yamlstar/index.coffee

@@ -1,4 +0,0 @@
-require 'yaml'
-
-class yamlstar
-  version: '0.0.1'