https://github.com/rising3/smart-entity-js
A smart entity that implements generic methods such as clone(), toJSON(), and fromJSON().
https://github.com/rising3/smart-entity-js
clone entity fromjson jsonschema tojson
Last synced: 2 months ago
JSON representation
A smart entity that implements generic methods such as clone(), toJSON(), and fromJSON().
- Host: GitHub
- URL: https://github.com/rising3/smart-entity-js
- Owner: rising3
- License: apache-2.0
- Created: 2025-03-20T17:09:25.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-03-29T08:40:06.000Z (6 months ago)
- Last Synced: 2025-03-29T09:28:30.913Z (6 months ago)
- Topics: clone, entity, fromjson, jsonschema, tojson
- Language: TypeScript
- Homepage:
- Size: 84 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# smart-entity-js
[](https://github.com/rising3/smart-entity-js/actions/workflows/build.yml)
[](LICENSE)
A smart entity that implements generic methods such as clone(), toJSON(), and fromJSON().
## Requirements
- Node.js 18 or higher
## How to install
To install:
```
npm i @rising3/smart-entity-js
```
## Getting started
### How to use library
Create an entity by inheriting the SmartEntity class.
As an example, create a Person class and an Address class.
#### Person Class
``` typescript
class Person extends SmartEntity {
protected _maskableFields = ["name"];
protected _requiredFields = ["name"];
protected _schemaHints = {
id: { type: "string" },
name: { type: "string" },
age: { type: "number", nullable: true },
isActive: { type: "boolean", nullable: false },
createAt: { type: "number" },
hobbies: { type: "array", nullable: true },
address: { type: "object", schema: Address.getJsonSchema(), nullable: true },
};
constructor(
public id: string = crypto.randomUUID(),
public name: string = "",
public age?: number,
public isActive: boolean = true,
public createAt: number = Date.now(),
public hobbies: string[] = [],
public address?: Address
) {
super();
}
static example(): Person {
return new Person(
crypto.randomUUID(),
"Alice",
Math.floor(Math.random() * 100) + 1,
true,
Date.now(),
["reading", "video game"],
Address.example()
);
}
}
```
#### Address Class
``` typescript
class Address extends SmartEntity
{
protected _maskableFields = ["postalCode", "address"];
protected _requiredFields = ["postalCode", "address"];
protected _schemaHints = {
postalCode: { type: "string" },
address: { type: "string" },
};
constructor(
public postalCode: string = "",
public address: string = ""
) {
super();
}
static example(): Address {
return new Address(
"123-4567",
"tokyo"
);
}
}
```
### Generic methods
#### static getJsonSchema()
Get the JSON schema for the entity.
The JSON schema is created based on the hints defined in the entity.
``` typescript
const schema = Person.getJsonSchema();
```
result:
``` json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": false
},
"name": {
"type": "string",
"nullable": false
},
"age": {
"type": "number",
"nullable": true
},
"isActive": {
"type": "boolean",
"nullable": false
},
"createAt": {
"type": "number",
"nullable": false
},
"hobbies": {
"type": "array",
"nullable": true
},
"address": {
"type": "object",
"properties": {
"postalCode": {
"type": "string",
"nullable": false
},
"address": {
"type": "string",
"nullable": false
}
},
"required": [
"postalCode",
"address"
],
"additionalProperties": false,
"nullable": true
}
},
"required": [
"name"
],
"additionalProperties": false
}
```
#### static fromJSON()
Create an instance of the Person class from JSON.
Validate the JSON using a JSON Schema.
``` typescript
const json = JSON.stringify({
id: "b46021c4-2cf2-4167-a31c-50c9d297e6b8",
name: "Alice",
age: 1,
isActive: false,
createAt: 1742483906966,
hobbies: ["reading", "video game"],
address: { postalCode: "123-4567", address: "tokyo" },
});
const person = Person.from(json);
```
#### static example()
Create an instance of the example Person class.
``` typescript
const person = Person.example();
```
#### toJSON()
Get JSON from an instance of the Person class.
##### compact JSON
``` typescript
person.toJSON();
```
result:
``` json
{"id":"e110860c-c201-4977-8f5f-97c7eb0e31ba","name":"Alice","age":5,"isActive":true,"createAt":1742492794876,"hobbies":["reading","video game"],"address":{"postalCode":"123-4567","address":"tokyo"}}
```
##### pretty JSON
``` typescript
person.toJSON(true);
```
result:
``` json
{
"id": "e110860c-c201-4977-8f5f-97c7eb0e31ba",
"name": "Alice",
"age": 5,
"isActive": true,
"createAt": 1742492794876,
"hobbies": [
"reading",
"video game"
],
"address": {
"postalCode": "123-4567",
"address": "tokyo"
}
}
```
##### masked JSON
``` typescript
person.toJSON(true, true);
```
result:
``` json
{
"id": "e110860c-c201-4977-8f5f-97c7eb0e31ba",
"name": "********",
"age": 5,
"isActive": true,
"createAt": 1742492794876,
"hobbies": [
"reading",
"video game"
],
"address": {
"postalCode": "********",
"address": "*****"
}
}
```
#### validate()
Validate an instance of the Person class using a JSON Schema.
``` typescript
const person = new Person();
person.validate(); // Throw Error
```
#### clone()
Create a clone by deep copying an instance of the Person class.
``` typescript
const clone = person.clone();
```
## How to build from source
### prerequisites
node.js, npm, git need to be installed.
```sh
git clone https://github.com/rising3/smart-entity-js.git
cd smart-entity-js
npm i
npm run test
npm run build
```
To run the example:
```
npm start
```
## License
[Apache 2.0](LICENSE)