internet-object

Internet Object

Welcome to the official JavaScript repository for Internet Object, a lean, robust, and schema-first data interchange format designed for the Internet. As a well-structured alternative to JSON, Internet Object offers a user-friendly API for JavaScript and TypeScript, making it effortless to work with Internet Object documents.

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

🚧 Work In Progress - API MAY CHANGE

Example Usage

The example below illustrates the usage of Internet Object for parsing a basic internet object document. Please be aware that the API is still in development and has not been officially released. This is purely for demonstration purposes.

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

In Internet Object, objects serve as the fundamental building blocks. There are numerous ways to create these objects. Below are a few 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

Often, before transmitting a document to a remote location, it's crucial to validate the document against a predefined schema or definition. If the validation process detects an invalid value, it will throw a ValidationError.

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

Core Tokenization and Parsing Interfaces

During the tokenization and parsing process, if an error is encountered, an exception is promptly thrown. This exception pinpoints the exact location of the error. Furthermore, the exception may also detail the specific token that instigated 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

🚧 Pull requests are currently not accepted. Development is ongoing, and the API is still under finalization. Once the API is stable, we will welcome contributions. Please note that the following instructions are for reference only.

1. Fork repository from https://github.com/maniartech/InternetObject-js
2. Install dependencies yarn install
3. Make changes in ./src
4. Update tests in ./tests/
5. Run tests, yarn test
6. Send pull request(s)

For a comprehensive understanding of Internet Object, refer to the official specification available at docs.InternetObject.org.

ISC License:

© 2018-2024 ManiarTech®️. All rights reserved.