Internet-object NPM

Internet Object

This is the official repository for Internet Object in JavaScript. Internet Object is a thin, robust, schema-first yet simple data interchange format for the Internet. It is the best well-planned alternative to JSON. This JavaScript/TypeScript library provides a simple and easy-to-use API to work with Internet Object documents.

For specification and more information, visit InternetObject.org Docs.

🚧 Work In Progress - API MAY CHANGE ⚠️

Example Usage

The following example demonstrates how to use Internet Object to parse a simple internet object document. Please note that the API is not yet ready and published. This is just a demonstration.

Parsing strings into documents

import { ioDocument } from 'internet-object';

const doc = ioDocument`
  name, age, gender, address: {street, city, state, zip}
  ---
  ~ John, 25, M, {123 Main St, Anytown, CA, 12345}
  ~ Jane, 30, F, {456 Main St, Anytown, CA, 12345}`;

console.log(doc);

Parsing with separate definitions

import { ioDefinitions, ioDocument } from 'internet-object';

const defs = ioDefinitions`
  ~ @red: 0xff0000
  ~ @blue: 0x0000ff
  ~ @green: 0x00ff00
  ~ $schema: {
    name, age, gender, color, address: {street, city, state, zip}
  }`;

// Parse document with external definitions
const doc = ioDocument.with(defs)`
  ~ John, 25, M, @green, {123 Main St, Anytown, CA, 12345}
  ~ Jane, 30, F, @blue, {456 Main St, Anytown, CA, 12345}`;

Working with documents

import { Collection, Document, InternetObject } from 'internet-object';

const collection = new Collection();
collection.push(
  new InternetObject("John Doe", 25, "M", "@green", new io.Object("123 Main St", "Anytown", "CA", "12345")),
  new InternetObject("Jane Doe", 30, "F", "@blue", new io.Object("456 Main St", "Anytown", "CA", "12345")),
)

const doc = new Document();
doc.data.pushToFirst(collection);

Building Objects

Objects are the core and the building blocks in Internet Object. Objects can be created in many ways. The following are some examples.

// Using the Object constructor
const o1 = new InternetObject("John Doe", 25, "M", "@green", new io.Object("123 Main St", "Anytown", "CA", "12345"));

// Using the Object constructor with an array
const arr = [ "John Doe", 25, "M", "@green", new io.Object("123 Main St", "Anytown", "CA", "12345") ]
const o2 = new io.Object(...arr);

// Using string interpolation
const o3 = io.object`John Doe, 25, M, @green, {123 Main St, Anytown, CA, 12345}`;

// Using the Object.import method
const o4 = InternetObject.import({
    name: "John Doe",
    age: 25,
    gender: "M",
    color: "@green",
    address: {
      street: "123 Main St",
      city: "Anytown",
      state: "CA",
      zip: "12345"
    }
  })

Validate Document with external schema

Many times before sending a document to a remote, it is necessary to validate the document against a schema/defs. While validating, if an invalid value is encountered, a ValidationError is thrown.

try {
  doc.validate(defs);
  console.log("Document is valid");
} catch (e) {
  console.log(e);
}

Core Tokenization and Parsing Interfaces

While performing tokenization and parsing, if an error is encountered, an exception is thrown. The exception contains the line and column number of the error. The exception may contain the token that caused the error.

const tokens = io.parser.tokenize(code)
const ast = io.parser.parse(tokens)

// Convert AST to Document
const doc = io.parser.compile(ast)

// Convert AST to Definitions
const defs = io.parser.compileDefs(ast)

Work in Progress Status

Tokenizer
AST Parser
Schema
- Parsing
- Validation
Data Types
- Numbers
  - Decimal Numbers
  - Binary Number
  - Hex Numbers
  - Octal Numbers
- Strings
  - Open Strings
  - Regular Strings
  - Raw Strings
- Boolean and Nulls
- DateTime
  - DateTime
  - Date
  - Time
- Binary Data
Collections
Definitions
Serialization (WIP)
API Interface Finalization (WIP)
Errors Standardization (WIP)
Optimization (WIP)
Testing (WIP)

Development Process

⚠️ Not currently accepting any pull requests. The development is in progress and the API is not yet finalized. Once the API is finalized, the repository will be open for contributions. Following instructions are just for reference.