protoobject

ProtoObject

A universal class for creating any JSON objects and simple manipulations with them.

Just inherit from this class and easily organize your work with data. This can be data storage in an SQL/NoSQL database, data storage in localStorage/sessionStorage, simple transfer of data serialization on one side and the same idle deserialization of data on the other side. You can write your own ProtoBuffer protocol on top of this library and use it for RPC or to write a universal data library for FrontEnd and BackEnd.

Think of it as a data framework.

Inspired by gRPC and Firebase.

INSTALL

 npm i protoobject --save

MODULE FORMATS

This library supports both CommonJS and ESM (ES Modules) formats:

CommonJS

const { ProtoObject, StaticImplements, protoObjectFactory } = require('protoobject');

ES Modules (ESM)

import { ProtoObject, StaticImplements, protoObjectFactory } from 'protoobject';

The library automatically provides the correct format based on your project configuration. No additional setup required!

🌐 BROWSER COMPATIBILITY

ProtoObject works in both Node.js and Browser environments:

Browser Usage

For browser compatibility, use the browser-specific import:

// Browser-compatible imports only (excludes Node.js-specific modules)
import { 
  ProtoObject, 
  StaticImplements,
  protoObjectFactory 
} from 'protoobject/browser';

Node.js Usage

For Node.js, use the full import with all modules:

// Full import with all modules including Node.js-specific
import { 
  ProtoObject,
  ProtoObjectSQLite,
  ProtoObjectTCP,
  ProtoObjectCrypto,
  ProtoObjectFS,
  ProtoObjectStream
} from 'protoobject';

Browser Support

• ✅ Chrome 80+
• ✅ Firefox 75+
• ✅ Safari 13+
• ✅ Edge 80+
• ✅ ES6+ and ES Modules support

What Works in Browser

• ✅ Core ProtoObject functionality
• ✅ JSON serialization/deserialization
• ✅ localStorage/sessionStorage integration
• ✅ Fetch API integration
• ✅ IndexedDB integration
• ✅ WebSocket integration

What's Node.js Only

• ❌ ProtoObjectSQLite (use IndexedDB in browser)
• ❌ ProtoObjectTCP (use WebSockets/Fetch in browser)
• ❌ ProtoObjectCrypto (use Web Crypto API in browser)
• ❌ ProtoObjectFS (use localStorage/IndexedDB/Fetch in browser)
• ❌ ProtoObjectStream (use browser streams or fetch in browser)

📚 EXAMPLES

See the examples/ directory for comprehensive usage examples:

• Browser Examples - Browser compatibility with interactive demo
• JavaScript Examples - Plain JavaScript usage with CommonJS
• TypeScript Examples - Type-safe usage with decorators and interfaces
• SQL Database Examples - Database integration patterns

🧪 TESTING

Run all tests:

npm test

Run specific test suites:

npm run test:ts    # TypeScript tests
npm run test:js    # JavaScript tests  
npm run test:sql   # SQL database tests

DOCS

The main methods of the ProtoObject class

These methods ensure that the class and its heirs interact with the external system and will not contain backward incompatible changes.

type of the property	name of the property	description
static	fromJSON	A method for converting a simple json to ProtoObject class or its heir
dynamic	toJSON	A method for converting a ProtoObject class or its heir to simple json
dynamic	toString	A method for converting a ProtoObject class or its heir to a string
dynamic	copy	Copying a ProtoObject class or its heirs
dynamic	assign	Deep assign data to an instance of the ProtoObject class or its heir
static	recordTransformer	Factory for creating a data transformer for the ProtoObject class or its heir
static	collectionTransformer	Factory for creating a data transformer for the array of ProtoObject classes or its heirs

The auxiliary methods of the ProtoObject class

These methods ensure the operation of the class itself and can change significantly over time.

type of the property	name of the property	description
static	getProperties	Get all properties of an object and its prototypes
static	getEnumerableProperties	Get all enumerable properties of an object and its prototypes
static	recursiveAssign	A recursive function for assigning properties to an object or returning a property if it is not interchangeable
static	deepAssign	Deep assign data to an instance of the ProtoObject class or its heir
static	valueToJSON	The converter of values into simple types
static	valueFromJSON	The converter of simple types into values

JavaScript

Creating an heir class

JavaScript - Creating an heir class using inheritance

Note that you cannot use static method validation using a decorator in JavaScript, TypeScript provides more features.

Note the call to this.assign(data); in the constructor of your own class. This is due to the code build, which causes your class to first call super(data); and then apply the value of the properties specified in the class (if the value is not specified, undefined will be applied). This is the reason why super(data); will not make an assignment for the properties specified in your class.

class UserAddress extends ProtoObject {
  constructor(data) {
    if (data) this.assign(data);
    return this;
  }

  country;

  postCode;
}

JavaScript - Creating an heir class using a factory

You can skip fields with standard types String, Number, Boolean and use a superclass converters (UserRights?.prototype?.toJSON?.call(this) and ProtoObject.fromJSON(data)) for these types, but you must implement the conversion of the remaining types manually.

const UserRights = protoObjectFactory({
  fromJSON(data) {
    return new this({
      ...ProtoObject.fromJSON(data),
      updatedAt: new Date(data?.updatedAt),
    });
  },
  toJSON() {
    return {
      ...UserRights?.prototype?.toJSON?.call(this),
      updatedAt: this.updatedAt?.toJSON(),
    };
  },
});

JavaScript - Creating an heir class using inheritance with conversion of additional data types

Note that you cannot use static method validation using a decorator in JavaScript, TypeScript provides more features.

Note the call to this.assign(data); in the constructor of your own class. This is due to the code build, which causes your class to first call super(data); and then apply the value of the properties specified in the class (if the value is not specified, undefined will be applied). This is the reason why super(data); will not make an assignment for the properties specified in your class.

You can skip fields with standard types String, Number, Boolean and use a superclass converters (super.toJSON.call(this) and super.fromJSON(data)) for these types, but you must implement the conversion of the remaining types manually.

class User extends ProtoObject {
  constructor(data) {
    super(data);
    if (data) this.assign(data);
    return this;
  }

  id;

  email;

  createdAt;

  photo;

  address;

  toJSON() {
    return {
      ...super.toJSON.call(this),
      createdAt: this.createdAt.toJSON(),
      photo:
        this.photo instanceof Buffer ? this.photo.toString("hex") : undefined,
      address:
        this.address instanceof UserAddress ? this.address.toJSON() : undefined,
      rights:
        this.rights instanceof UserRights ? this.rights?.toJSON() : undefined,
    };
  }

  static fromJSON(data) {
    return new User({
      ...super.fromJSON(data),
      createdAt:
        typeof data.createdAt === "string"
          ? new Date(data.createdAt)
          : undefined,
      photo:
        typeof data.photo === "string"
          ? Buffer.from(data.photo, "hex")
          : undefined,
      address: data.address ? UserAddress.fromJSON(data.address) : undefined,
      rights: data.rights ? UserRights.fromJSON(data.rights) : undefined,
    });
  }
}

TypeScript

Creating an heir class

TypeScript - Creating an heir class using inheritance

Note that to check the static properties of a class, you can use the decorator @StaticImplements<ProtoObjectStaticMethods<User>>().

Note the call to this.assign(data); in the constructor of your own class. This is due to the code build, which causes your class to first call super(data); and then apply the value of the properties specified in the class (if the value is not specified, undefined will be applied). This is the reason why super(data); will not make an assignment for the properties specified in your class.

@StaticImplements<ProtoObjectStaticMethods<UserAddress>>()
export class UserAddress extends ProtoObject<UserAddress> {
  constructor(data?: Partial<UserAddress>) {
    super(data);
    if (data) this.assign(data);
    return this;
  }

  country!: string;

  postCode!: string;
}

TypeScript - Creating an heir class using a factory

You can skip fields with standard types String, Number, Boolean and use a superclass converters (UserRights?.prototype?.toJSON?.call(this) and ProtoObject.fromJSON(data)) for these types, but you must implement the conversion of the remaining types manually.

interface IUserRights extends ProtoObject<IUserRights> {
  isAdmin: boolean;
  updatedAt: Date;
}
const UserRights = protoObjectFactory<IUserRights>({
  fromJSON(data) {
    return new this({
      ...ProtoObject.fromJSON(data),
      updatedAt: new Date(data?.updatedAt),
    });
  },
  toJSON() {
    return {
      ...UserRights?.prototype?.toJSON?.call(this),
      updatedAt: this.updatedAt?.toJSON(),
    };
  },
});

TypeScript - Creating an heir class using inheritance with conversion of additional data types

Note that to check the static properties of a class, you can use the decorator @StaticImplements<ProtoObjectStaticMethods<User>>().

Note the call to this.assign(data); in the constructor of your own class. This is due to the code build, which causes your class to first call super(data); and then apply the value of the properties specified in the class (if the value is not specified, undefined will be applied). This is the reason why super(data); will not make an assignment for the properties specified in your class.

You can skip fields with standard types String, Number, Boolean and use a superclass converters (super.toJSON.call(this) and super.fromJSON(data)) for these types, but you must implement the conversion of the remaining types manually.

@StaticImplements<ProtoObjectStaticMethods<User>>()
class User extends ProtoObject<User> {
  constructor(data?: Partial<User>) {
    super(data);
    if (data) this.assign(data);
    return this;
  }

  id!: string;

  email!: string;

  createdAt!: Date;

  photo?: Buffer;

  address?: UserAddress;

  rights?: IUserRights;

  public toJSON(): { [key: string]: any } {
    return {
      ...super.toJSON.call(this),
      createdAt: this.createdAt.toJSON(),
      photo:
        this.photo instanceof Buffer ? this.photo.toString("hex") : undefined,
      address:
        this.address instanceof UserAddress ? this.address.toJSON() : undefined,
      rights:
        this.rights instanceof UserRights ? this.rights?.toJSON() : undefined,
    };
  }

  public static fromJSON<User>(data: { [key: string]: unknown }): User {
    return new User({
      ...(super.fromJSON<any>(data) as User),
      createdAt:
        typeof data.createdAt === "string"
          ? new Date(data.createdAt)
          : undefined,
      photo:
        typeof data.photo === "string"
          ? Buffer.from(data.photo, "hex")
          : undefined,
      address: data.address
        ? UserAddress.fromJSON<UserAddress>(
            data.address as { [key: string]: unknown }
          )
        : undefined,
      rights: data.rights ? UserRights.fromJSON(data.rights) : undefined,
    }) as unknown as User;
  }
}

An example of the implementation of the SQL database base class

This is an example of creating a basic (abstract) class for working with an SQLite database. Below is an example of an heir of this class, which is a table entry.

import { randomUUID } from "node:crypto";
import { DatabaseSync } from "node:sqlite";
import {
  ProtoObject,
  ProtoObjectStaticMethods,
  StaticImplements,
} from "protoobject";

export enum RecordState {
  ACTIVE,
  DELETED,
}

export interface BaseRecordStaticMethods<T extends BaseRecord<T>>
  extends ProtoObjectStaticMethods<T> {
  table: string;
  getById<T extends BaseRecord<T>>(
    db: DatabaseSync,
    id: BaseRecord<T>["id"]
  ): Promise<T | undefined>;
}

@StaticImplements<BaseRecordStaticMethods<BaseRecord<any>>>()
export class BaseRecord<T extends BaseRecord<T>> extends ProtoObject<T> {
  constructor(data?: Partial<T>) {
    super(data);
    if (data) this.assign(data);
    if (typeof this.record_state === "undefined")
      this.record_state = RecordState.ACTIVE;
    if (!this.id) this.id = randomUUID();
    const dt = new Date();
    if (!this.created_at) this.created_at = dt;
    if (!this.updated_at) this.updated_at = dt;
    return this;
  }

  public static table = `base`;

  public id!: string;

  public created_at!: Date;

  public updated_at!: Date;

  public record_state!: RecordState;

  public static async getById<T extends BaseRecord<T>>(
    db: DatabaseSync,
    id: BaseRecord<T>["id"]
  ): Promise<T | undefined> {
    const dbRecord = (await db
      .prepare(`SELECT * FROM ${this.table} WHERE id = ?`)
      .get(id)) as Partial<T>;
    return dbRecord ? this.fromJSON<T>(dbRecord) : undefined;
  }

  public async reload(db: DatabaseSync): Promise<T> {
    const classNode = this.constructor as BaseRecordStaticMethods<T>;
    const dbRecord = await classNode.getById<T>(db, this.id);
    if (!dbRecord) throw new Error("Not Found");
    return this.assign(classNode.fromJSON(dbRecord));
  }

  public async insert(db: DatabaseSync): Promise<void> {
    const classNode = this.constructor as BaseRecordStaticMethods<T>;
    this.created_at = new Date();
    this.updated_at = new Date();
    const jsonData = this.toJSON();
    await Promise.resolve(
      db
        .prepare(
          `INSERT INTO ${classNode.table} (${Object.keys(jsonData).join(", ")}) VALUES (${Object.keys(
            jsonData
          )
            .map((e, i) => `?`)
            .join(", ")})`
        )
        .run(...Object.values(jsonData))
    );
    return;
  }

  public async update(db: DatabaseSync): Promise<void> {
    const classNode = this.constructor as BaseRecordStaticMethods<T>;
    this.updated_at = new Date();
    const jsonData = this.toJSON();
    delete jsonData.id;
    await Promise.resolve(
      db
        .prepare(
          `UPDATE ${classNode.table} SET ${Object.keys(jsonData)
            .map((e, i) => `${e} = ?`)
            .join(", ")} WHERE id = ?`
        )
        .run(...Object.values(jsonData), this.id)
    );
    return;
  }

  public async softDelete(db: DatabaseSync): Promise<void> {
    this.record_state = RecordState.DELETED;
    this.updated_at = new Date();
    await this.update(db);
    return;
  }

  public async delete(db: DatabaseSync): Promise<void> {
    const classNode = this.constructor as BaseRecordStaticMethods<T>;
    const jsonData = this.toJSON();
    delete jsonData.id;
    await Promise.resolve(
      db.prepare(`DELETE FROM ${classNode.table} WHERE id = ?`).run(this.id)
    );
    return;
  }

  public static fromJSON<T>(data: { [key: string]: unknown }) {
    return new this({
      ...super.fromJSON(data),
      created_at:
        typeof data.created_at === "string"
          ? new Date(data.created_at)
          : undefined,
      updated_at:
        typeof data.updated_at === "string"
          ? new Date(data.updated_at)
          : undefined,
    }) as T;
  }

  public toJSON(): { [key: string]: any } {
    return {
      ...super.toJSON.call(this),
      created_at: this.created_at?.toJSON(),
      updated_at: this.updated_at?.toJSON(),
    };
  }
}

An example of the implementation of an heir from the base class of the SQL database

An example of a simple implementation of a data class based on a base class.

import { randomUUID } from "crypto";
import { StaticImplements } from "protoobject";
import { BaseRecord, BaseRecordStaticMethods } from "./example-base-class";

@StaticImplements<BaseRecordStaticMethods<ApplicationRecord>>()
export class ApplicationRecord extends BaseRecord<ApplicationRecord> {
  constructor(data?: Partial<ApplicationRecord>) {
    super(data);
    if (data) this.assign(data);
    if (!this.api_key) this.api_key = randomUUID();
  }

  public static override table: string = `applications`;

  public api_key!: string;

  public app_name!: PublicKeyCredentialCreationOptions["rp"]["name"];

  public app_params!: { [key: string]: string | number | boolean | null };

  public static fromJSON<T>(data: { [key: string]: unknown }) {
    return new ApplicationRecord({
      ...super.fromJSON(data),
      app_params:
        typeof data?.app_params === "string"
          ? JSON.parse(data.app_params)
          : undefined,
    }) as T;
  }

  public toJSON(): { [key: string]: any } {
    return {
      ...super.toJSON.call(this),
      app_params: this.app_params ? JSON.stringify(this.app_params) : undefined,
    };
  }
}

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Development Setup

git clone https://github.com/siarheidudko/protoobject.git
cd protoobject
npm install
npm run build
npm test

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📝 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [e-mail]

💝 Support This Project

If ProtoObject helps you build amazing applications, consider supporting its development:

• ☕ Buy me a coffee
• 💳 PayPal
• 🎯 Patreon
• 🌐 More options

Your support helps maintain and improve Redux Cluster for the entire community!

Made with ❤️ by Siarhei Dudko