webject v1.3.9

Webject

Share (and sync) Objects Online with the power of websockets. Keys, Values AND References. Webject is short for Web Object and it really is a system for sharing objects on the web. Someone can host an object, then create and configure an authToken, enabling clients to connect to the object with the permissions/constraints defined by the respective authToken it a client connects with. Why Webject? This tool has usage for whenever one wishes to either collaborate on or simply share/sync real time data remotely with ease >:D

• Please note: To view example usage of the modules this library provides, please refer to the tests

Installation

Multiple ways

• Download Github Package as ZIP
• git cli: git clone https://github.com/Y0ursTruly/webject.git
• npm cli: npm install webject
• browser/frontend script tag: <script src="https://cdn.jsdelivr.net/npm/webject@latest/for_browser.min.js"></script>

Importing

const {
  serve, //doesn't exist on browser
  connect, //is a global variable when browser script is loaded
  sync, //doesn't exist on browser
  desync, //doesn't exist on browser
  objToString, //is a global variable when browser script is loaded
  stringToObj, //is a global variable when browser script is loaded
  objValueFrom, //is a global variable when browser script is loaded
  setConsistency //doesn't exist on browser
} = require("webject");

ADVISORY

If you (the developer) wish to use this as a database (achieve persistence using the sync module), in ACID, this library only enforces D without any work and A,C,D when utilising a given setConsistency module which should be used to declare if an object is safe for saving or not (if a transaction is complete or not). Isolation must be handled by you, the developer, since this library is designed to allow objects to be shared/synced among multiple clients concurrently.

Modules

• if syncList already includes filePath, the syncList's object already stored one to one relation between a unique object and a unique filePath is how sync function works do not worry about "should I desync when finished using sync" because there is a counter acting as the amount of times the function was called with a unique filePath

• else if obj was given -- if filePath has webject serialised/stringified content, obj modified by contents of filePath -- else, the unmodified obj

• else (obj was NOT given) -- if filePath has webject serialised/stringified content, solely the parsed value of filePath contents -- else, an empty object {}

Structures

Event

Let's look at what is given to yourReaction when you call the addListener function (which is a method of what is returned after calling the serve function)

{
  token: Object, //an authToken's object or null
  socket: Object, //a websocket client object or null
  type: String, //a string(either "edit", "connect", or "disconnect")
  lock: Function, //prevents more connections to an authToken passed in OR this event's token.authToken if called with none given
  unlock: Function, //allows new connections to an authToken passed in OR this event's token.authToken if called with none given
  preventDefault: Function //stops passing the event to other listeners after (the listener that calls this will be the last listener to see the event)
}

The or null parts with token and socket only apply to if the event is of type edit. These would be null when an edit on an object occured on the server side, thus there is no client token and socket related/responsible for the event

Token

The authToken object, highly integral to this repository because authTokens configure and define how others connect/sync to your objects. Let's look at its structure

{
  authToken: String,
  filter: Number OR Function,
  clients: Map,
  object: Object,
  locked: Boolean,
  dispatch: Function,
  encoder: Function OR null,
  decoder: Function OR null
}

This is authToken string, next is a filter which is either 1,2,3 or a function that would filter every part of an incoming edit, followed by a Map of websocket connections to this authToken, followed by the object that this authToken is meant to shared, followed by if it's locked, then a dispatch function responsible for this authToken (many authTokens might have the same dispatcher responsible for it), followed by an optional encoder and decoder for custom encoding.

Part

What is meant by part? objToString(someObj) always returns JSON.stringify(someArray) where someArray is made up of parts. Each part comes in the format

the value in ONE index(part) of an objToString array are 1 of the following types:

[path] //delete
[path,data] //value
[path,refPath,num] //reference
[path,data,0,tag] //custom datatype value

- path is array of strings to represent a location
- data is an instance of a datatype to represent a value
- refPath is an index to a referred path located in another index(part) or the path array itself
- num is a number which can be 3 options: 0=not mentioned, 1=mentioned as path, 2=mentioned as reference
- tag is the [Symbol.toStringTag] property of a value and is used for TypedArray, BigInt, Symbol and undefined(which has no [Symbol.toStringTag] but isn't JSON)

Coding

This is an object of two functions: encode and decode. Each function must be robust since they can receive and also return ONE of two types of data: either string or buffer. In essence, they must have accomodations for two data types. Only one argument is given, data.

{
  function encode(data/*instanceof Buffer or String*/){return an instanceof Buffer or String},
  function decode(data/*instanceof Buffer or String*/){return an instanceof Buffer or String},
}