feat: zod interoperability and better docs

Author: ProGM

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project made by Monade Team are documented in this file. For info refer to team@monade.io
 
+## [1.1.0] - 2023-09-03
+
+### Added
+- Zod interoperability with `defineModel()`
+- Improved toJSON method
+- Improved docs
+
 ## [1.0.2] - 2022-08-16
 ### Added
 - Utility interface `DTO<T>`

README.md

@@ -3,15 +3,86 @@
 
 # @monade/json-api-parser
 
-A parser for [JSON:API](https://jsonapi.org/) format that maps data to models using decorators, inspired by retrofit.
+This library provides a parser for the [JSON:API](https://jsonapi.org/) format, enabling seamless mapping of JSON data to TypeScript/JavaScript models using decorators.
+
+## Table of Contents
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+    - [Model Declaration](#model-declaration)
+    - [The Parser](#the-parser)
+- [Full Example](#full-example)
+- [Zod Interoperability (Experimental)](#zod-interoperability-experimental)
+- [TODO](#todo)
+
 
 ## Installation
 
+Install the package via npm:
+
 ```bash
   npm install @monade/json-api-parser
 ```
 
-## Example usage
+## Quick Start
+To get started, simply declare your models using the `@JSONAPI` and `@Attr` decorators and use the `Parser` class to parse JSON:API data.
+
+```typescript
+import { JSONAPI, Attr, Parser } from "@monade/json-api-parser";
+
+@JSONAPI("posts")
+class Post {
+  @Attr() title: string;
+}
+
+const jsonData = /* fetch your JSON:API data here */;
+const parsedData = new Parser(jsonData).run<Post[]>();
+```
+
+## Features
+### Models declaration
+**`@JSONAPI(type: string)`**
+
+This decorator acts as the entry point for declaring a JSON:API model. It maps a JSON:API object type to the decorated class.
+
+```typescript
+@JSONAPI("posts")
+class Post extends Model {}
+```
+
+**`@Attr([name?: string, options?: { parser?: Function, default?: any }])`**
+
+This decorator is used for declaring attributes on a JSON:API model. You can optionally specify a different name for the attribute, a default value and a parser function to transform the data.
+
+```typescript
+@JSONAPI("posts")
+class Post extends Model {
+  @Attr() title: string;
+}
+```
+
+**`@Rel([name?: string, options?: { parser?: Function, default?: any }])`**
+
+Use this decorator to declare relationships between JSON:API models. You can optionally specify a different name for the relationship, a default value and a parser function to transform the data.
+
+```typescript
+@JSONAPI("posts")
+class Post extends Model {
+  @Rel() author: User;
+}
+```
+
+### The Parser
+The Parser class is responsible for transforming JSON:API objects into instances of the declared models. To use it, create a new instance of `Parser` and call its `run<T>` method.
+
+Example:
+Usage:
+```typescript
+const jsonData = await fetch('https://some-api.com/posts').then(e => e.json());
+const parsedData = new Parser(jsonData).run<Post[]>();
+```
+
+## Full Example
 
 ```typescript
 import { Attr, JSONAPI, Model, Rel } from "@monade/json-api-parser";
@@ -40,15 +111,55 @@ class User extends Model {
 }
 ```
 
+## Zod Interoperability [EXPERIMENTAL]
+This library also offers experimental support for [Zod](https://zod.dev/), allowing for runtime type-checking of your JSON:API models.
+
+```typescript
+import { declareModel, InferModel, modelOfType } from "@monade/json-api-parser/zod";
+
+const UserSchema = declareModel(
+  "users",
+  {
+    attributes: z.object({
+      firstName: z.string(),
+      lastName: z.string(),
+      created_at: z.string().transform((v) => new Date(v)),
+    }),
+
+    relationships: z.object({
+      // Circular references must be addressed like this
+      favouritePost: modelOfType('posts'),
+    }),
+  }
+);
+
+const PostSchema = declareModel(
+  "posts",
+  {
+    attributes: z.object({
+      name: z.string(),
+      description: z.string(),
+      created_at: z.string().transform((v) => new Date(v)),
+      active: z.boolean().default(true),
+    }),
+    relationships: z.object({ user: UserSchema, reviewer: UserSchema })
+  }
+);
+
+type User = InferModel<typeof UserSchema>;
+type Post = InferModel<typeof PostSchema>;
+```
+
 ## TODO
-* Documentation
+* Improve Documentation
 * Edge case tests
+* Improve interoperability with zod
 
 
 About Monade
 ----------------
 
-![monade](https://monade.io/wp-content/uploads/2021/06/monadelogo.png)
+![monade](https://monade.io/wp-content/uploads/2023/02/logo-monade.svg)
 
 json-api-parser is maintained by [mònade srl](https://monade.io/en/home-en/).
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monade/json-api-parser",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A parser for JSON:API format that maps data to models using decorators, inspired by retrofit.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -22,6 +22,9 @@
     "ts-jest": "^27.1.4",
     "typescript": "^4.6.3"
   },
+  "optionalDependencies": {
+    "zod": "^3.0.0"
+  },
   "scripts": {
     "build": "rm -rf dist && rollup -c && tsc --emitDeclarationOnly",
     "prepublish:public": "yarn build",

src/Model.ts

@@ -1,8 +1,21 @@
 export class Model {
   id!: string;
+  _type!: string;
 
-  toJSON(): any {
-    return { ...this };
+  toJSON(maxDepth = 100): any {
+    const response: any = { ...this };
+    delete response._type;
+
+    for (const key in response) {
+      if (response[key] instanceof Model) {
+        if (maxDepth <= 0) {
+          delete response[key]
+        } else {
+          response[key] = response[key].toJSON(maxDepth - 1);
+        }
+      }
+    }
+    return response;
   }
 
   toFormData() {

src/Parser.ts

@@ -44,7 +44,7 @@ export class Parser {
     } else if ("data" in data && !("id" in data)) {
       return this.parse(data.data, data.included || included);
     } else {
-      return this.parseElement(data, included);
+      return this.parseElement(data as JSONModel, included);
     }
   }
 
@@ -57,78 +57,91 @@ export class Parser {
   parseElement<T>(element: JSONModel, included: JSONModel[]): T {
     const uniqueKey = `${element.id}$${element.type}`;
     if (this.resolved[uniqueKey]) {
-      return this.resolved[uniqueKey] as any;
+      return this.resolved[uniqueKey] as T;
     }
 
     const loadedElement = Parser.load(element, included);
 
     const model = Parser.$registeredModels.find(
       (e) => e.type === loadedElement.type
     );
+
+    const instance = new (model?.klass || Model)();
+    this.resolved[uniqueKey] = instance;
+
+    if (model && model.createFn) {
+      return model.createFn(instance, loadedElement, (relation) => this.parse(relation, included)) as T;
+    }
+
     const attrData = Parser.$registeredAttributes.find(
       (e) => e.klass === model?.klass
     );
     const relsData = Parser.$registeredRelationships.find(
       (e) => e.klass === model?.klass
     );
 
-    const instance = new (model?.klass || Model)();
+    instance.id = loadedElement.id;
+    instance._type = loadedElement.type;
 
-    this.resolved[uniqueKey] = instance;
+    this.parseAttributes(instance, loadedElement, attrData);
+    this.parseRelationships(instance, loadedElement, relsData, included);
 
-    instance.id = loadedElement.id;
-    for (const key in loadedElement.attributes) {
-      const parser = attrData?.attributes?.[key];
+    return instance as T;
+  }
+
+  private parseRelationships(instance: Model, loadedElement: JSONModel, relsData: RegisteredAttribute | undefined, included: JSONModel[]) {
+    for (const key in loadedElement.relationships) {
+      const relation = loadedElement.relationships[key];
+      const parser = relsData?.attributes?.[key];
       if (parser) {
         (instance as any)[parser.key] = parser.parser(
-          loadedElement.attributes[key]
+          this.parse(relation, included)
         );
       } else {
-        (instance as any)[key] = loadedElement.attributes[key];
-        debug(`Undeclared key "${key}" in "${loadedElement.type}"`);
+        (instance as any)[key] = this.parse(relation, included);
+        debug(`Undeclared relationship "${key}" in "${loadedElement.type}"`);
       }
     }
 
-    if (attrData) {
-      for (const key in attrData.attributes) {
-        const parser: RegisteredProperty = attrData.attributes[key];
+    if (relsData) {
+      for (const key in relsData.attributes) {
+        const parser: RegisteredProperty = relsData.attributes[key];
         if (!(parser.key in instance)) {
           if ("default" in parser) {
             (instance as any)[parser.key] = parser.default;
           } else {
-            debug(`Missing attribute "${key}" in "${loadedElement.type}"`);
+            debug(`Missing relationships "${key}" in "${loadedElement.type}"`);
           }
         }
       }
     }
+  }
 
-    for (const key in loadedElement.relationships) {
-      const relation = loadedElement.relationships[key];
-      const parser = relsData?.attributes?.[key];
+  private parseAttributes(instance: Model, loadedElement: JSONModel, attrData: RegisteredAttribute | undefined) {
+    for (const key in loadedElement.attributes) {
+      const parser = attrData?.attributes?.[key];
       if (parser) {
         (instance as any)[parser.key] = parser.parser(
-          this.parse(relation, included)
+          loadedElement.attributes[key]
         );
       } else {
-        (instance as any)[key] = this.parse(relation, included);
-        debug(`Undeclared relationship "${key}" in "${loadedElement.type}"`);
+        (instance as any)[key] = loadedElement.attributes[key];
+        debug(`Undeclared key "${key}" in "${loadedElement.type}"`);
       }
     }
 
-    if (relsData) {
-      for (const key in relsData.attributes) {
-        const parser: RegisteredProperty = relsData.attributes[key];
+    if (attrData) {
+      for (const key in attrData.attributes) {
+        const parser: RegisteredProperty = attrData.attributes[key];
         if (!(parser.key in instance)) {
           if ("default" in parser) {
             (instance as any)[parser.key] = parser.default;
           } else {
-            debug(`Missing relationships "${key}" in "${loadedElement.type}"`);
+            debug(`Missing attribute "${key}" in "${loadedElement.type}"`);
           }
         }
       }
     }
-
-    return instance as any;
   }
 
   static load(element: JSONModel, included: JSONModel[]) {

src/interfaces/RegisteredModel.ts

@@ -1,6 +1,10 @@
 import { Model } from "../Model";
+import { JSONModel } from "./JSONModel";
 
-export interface RegisteredModel {
+type CreateFunction = (instance: Model, modelData: JSONModel, resolverFn: (data: any) => Model | Model[] | null) => Model
+
+export type RegisteredModel = {
   type: string;
-  klass: typeof Model;
+  klass?: typeof Model;
+  createFn?: CreateFunction;
 }