@thing-king/metaform

Overview

@thing-king/metaform is a modular framework for defining, managing, and executing data processing units known as "Things." A Thing can either function as a handler, processing inputs and generating outputs, or serve as a type definition for validating and casting data. The framework is designed for flexibility and scalability, making it ideal for use in server-side applications, WebSocket-based client-server architectures, and dynamic environments.

Installation

Install the package via npm:

npm install @thing-king/metaform

ThingContext

The ThingContext is the core environment where Things are managed and executed. It acts as a collection of Things, handling tasks such as validation, execution, and data type casting. When you load a collection of Things into a ThingContext, you can execute any Thing within it, cast data types, and ensure that all operations conform to the defined metadata.

Example:

import { ThingLoader, ThingContext } from "@thing-king/metaform";

(async () => {
    const collection = await ThingLoader.loadCollection("./things");
    const result = await collection.execute("ExampleThing", {
        input1: "test",
        input2: 15,
    });
    console.log(result); // { result: true }
})();

Defining a Thing

A Thing is defined by exporting an object containing its metadata, inputs, outputs, and an optional handler function. Things can either be data handlers or custom type definitions.

1. Handlers

If a Thing is a handler, it processes inputs and generates outputs. The handler function is where the logic resides, and it operates based on the metadata-defined inputs and outputs.

2. Type Definitions

If a Thing is a custom data type, set type = true in the export. The handler function will then determine if the input can be cast to this type. It should return either true/false for a binary decision or a value between 0 and 1 representing the degree of similarity or certainty.

3. Input and Output Metadata

Input Metadata: Inputs can be defined using in, ins, or inputs. Use in for a single input, and ins or inputs for multiple inputs. The metadata should specify the type of each input.
Output Metadata: Outputs can be defined using out, outs, or outputs. Similar to inputs, out is used for a single output, while outs or outputs are for multiple outputs.
Default Behavior: If no specific input or output is provided, the framework assumes in as the default input and out as the default output.

Example:

Defining a Thing as a handler:

export default {
    name: "ExampleHandler",
    in: { type: "string" },
    out: { type: "boolean" },
    handler: async function (inputs) {
        return { out: inputs.in.length > 5 };
    },
};

Defining a Thing as a type:

export default {
    name: "ExampleType",
    type: true,
    in: { type: "any" },
    handler: async function (inputs) {
        return inputs.in instanceof Array ? 1 : 0; // Returns 1 if it's an array, otherwise 0.
    },
};

WebSocket Integration

@thing-king/metaform includes support for WebSocket-based communication, enabling distributed processing of Things across different environments.

Hosting a ThingContext via WebSocket

Create a WebSocket server to host a ThingContext, allowing clients to connect and execute Things remotely.

import { WebSocketTransport, ThingLoader } from "@thing-king/metaform";

(async () => {
    const collection = await ThingLoader.loadCollection("./things");
    const host = new WebSocketTransport.Host(collection, 8080);
    await host.start();
    console.log("WebSocket server is running on ws://localhost:8080");
})();

Connecting a WebSocket Client

A client can connect to the WebSocket server to send data and receive processed results:

import { WebSocketTransport } from "@thing-king/metaform";

(async () => {
    const client = new WebSocketTransport.Client("ws://localhost:8080");
    await client.start();
    const result = await client.send("ExampleHandler", { in: "teststring" });
    console.log(result); // { out: true }
})();