refactor(core): enhance class implementations and documentation (#162)

* refactor(core): update class implementations to implement options interfaces

- Updated .oxlintrc.json to enable @typescript-eslint/no-unsafe-declaration-merging rule
- Updated Api, Field, Operation, and Resource classes to implement their respective options interfaces.
- Declare all the fields in the classes instead of relying on interface declaration merging
- Update openapi3 test to take new fields order

Signed-off-by: J3m5 <[email protected]>

* refactor(core): replace assignSealed with Object.assign

- Removed assignSealed utility function.
- Updated constructors in Api, Field, Operation, and Resource classes to use Object.assign for property assignment.

Signed-off-by: J3m5 <[email protected]>

* refactor(docs): improve JSDoc comments following oxlint jsdoc plugin

- Edit .oxlintrc.json to enable jsdoc plugin
- Added parameter and return type annotations in buildEnumObject, getType, fetchJsonLd, parseHydraDocumentation, and handleJson functions.

Signed-off-by: J3m5 <[email protected]>

* refactor(core): export types from types.js in core index file

Signed-off-by: J3m5 <[email protected]>

* refactor(package.json): add exports for core module types and implementation

Signed-off-by: J3m5 <[email protected]>

* refactor(package.json): update lint:fix command and runtime version format

- Changed lint:fix command to include --fix-suggestions
- Updated runtime version format to include a space

Signed-off-by: J3m5 <[email protected]>

* refactor(oxlintrc): remove unused ESLint and Unicorn rules

Signed-off-by: J3m5 <[email protected]>

---------

Signed-off-by: J3m5 <[email protected]>

Author: J3m5

.oxlintrc.json

@@ -20,7 +20,8 @@
     "import",
     "eslint",
     "oxc",
-    "promise"
+    "promise",
+    "jsdoc"
   ],
   "rules": {
     "@typescript-eslint/no-empty-object-type": [
@@ -30,14 +31,13 @@
       }
     ],
     "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/no-unsafe-declaration-merging": "off",
+    "@typescript-eslint/no-unsafe-declaration-merging": "error",
     "eslint/arrow-body-style": ["error", "as-needed"],
     "eslint/curly": "error",
     "eslint/id-length": "off",
     "eslint/max-depth": "off",
     "eslint/max-lines": "off",
     "eslint/max-lines-per-function": "off",
-    "eslint/max-nested-callbacks": "off",
     "eslint/no-duplicate-imports": "off",
     "func-style": [
       "error",
@@ -90,9 +90,7 @@
         }
       }
     ],
-    "unicorn/no-nested-ternary": "off",
     "unicorn/no-null": "off",
-    "unicorn/number-literal-case": "off",
     "vitest/consistent-test-it": [
       "error",
       {

package.json

@@ -30,6 +30,11 @@
       "import": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./core": {
+      "types": "./lib/core/index.d.ts",
+      "import": "./lib/core/index.js",
+      "default": "./lib/core/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./lib/index.js",
@@ -47,7 +52,7 @@
     "knip": "knip",
     "knip:fix": "knip --fix",
     "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
+    "lint:fix": "oxlint --fix --fix-suggestions",
     "test": "vitest run",
     "test:coverage": "vitest --coverage",
     "test:watch": "vitest --watch",
@@ -86,7 +91,7 @@
     },
     "runtime": {
       "name": "node",
-      "version": ">=20"
+      "version": ">= 20"
     }
   }
 }

src/core/Api.ts

@@ -1,18 +1,20 @@
 import type { Resource } from "./Resource.js";
 import type { Nullable } from "./types.js";
-import { assignSealed } from "./utils/index.js";
 
 export interface ApiOptions
   extends Nullable<{
     title?: string;
     resources?: Resource[];
   }> {}
 
-export interface Api extends ApiOptions {}
-export class Api {
+export class Api implements ApiOptions {
   entrypoint: string;
+
+  title?: string | null;
+  resources?: Resource[] | null;
+
   constructor(entrypoint: string, options: ApiOptions = {}) {
     this.entrypoint = entrypoint;
-    assignSealed(this, options);
+    Object.assign(this, options);
   }
 }

src/core/Field.ts

@@ -1,6 +1,5 @@
 import type { Resource } from "./Resource.js";
 import type { Nullable } from "./types.js";
-import { assignSealed } from "./utils/index.js";
 
 export type FieldType =
   | "string"
@@ -40,18 +39,31 @@ export interface FieldOptions
     enum?: { [key: string | number]: string | number };
     reference?: string | Resource;
     embedded?: Resource;
-    required?: boolean;
     nullable?: boolean;
+    required?: boolean;
     description?: string;
     maxCardinality?: number;
     deprecated?: boolean;
   }> {}
 
-export interface Field extends FieldOptions {}
-export class Field {
+export class Field implements FieldOptions {
   name: string;
+
+  id?: string | null;
+  range?: string | null;
+  type?: FieldType | null;
+  arrayType?: FieldType | null;
+  enum?: { [key: string | number]: string | number } | null;
+  reference?: string | Resource | null;
+  embedded?: Resource | null;
+  nullable?: boolean | null;
+  required?: boolean | null;
+  description?: string | null;
+  maxCardinality?: number | null;
+  deprecated?: boolean | null;
+
   constructor(name: string, options: FieldOptions = {}) {
     this.name = name;
-    assignSealed(this, options);
+    Object.assign(this, options);
   }
 }

src/core/Operation.ts

@@ -1,5 +1,4 @@
 import type { Nullable } from "./types.js";
-import { assignSealed } from "./utils/index.js";
 
 export type OperationType = "show" | "edit" | "delete" | "list" | "create";
 
@@ -12,10 +11,16 @@ export interface OperationOptions
     deprecated?: boolean;
   }> {}
 
-export interface Operation extends OperationOptions {}
-export class Operation {
+export class Operation implements OperationOptions {
   name: string;
   type: OperationType;
+
+  method?: string | null;
+  expects?: any | null;
+  returns?: string | null;
+  types?: string[] | null;
+  deprecated?: boolean | null;
+
   constructor(
     name: string,
     type: OperationType,
@@ -24,6 +29,6 @@ export class Operation {
     this.name = name;
     this.type = type;
 
-    assignSealed(this, options);
+    Object.assign(this, options);
   }
 }

src/core/Resource.ts

@@ -2,29 +2,39 @@ import type { Field } from "./Field.js";
 import type { Operation } from "./Operation.js";
 import type { Parameter } from "./Parameter.js";
 import type { Nullable } from "./types.js";
-import { assignSealed } from "./utils/index.js";
 
 export interface ResourceOptions
   extends Nullable<{
     id?: string;
     title?: string;
     description?: string;
-    deprecated?: boolean;
     fields?: Field[];
     readableFields?: Field[];
     writableFields?: Field[];
-    parameters?: Parameter[];
     getParameters?: () => Promise<Parameter[]>;
     operations?: Operation[];
+    deprecated?: boolean;
+    parameters?: Parameter[];
   }> {}
 
-export interface Resource extends ResourceOptions {}
-export class Resource {
+export class Resource implements ResourceOptions {
   name: string;
   url: string;
+
+  id?: string | null;
+  title?: string | null;
+  description?: string | null;
+  fields?: Field[] | null;
+  readableFields?: Field[] | null;
+  writableFields?: Field[] | null;
+  getParameters?: (() => Promise<Parameter[]>) | null;
+  operations?: Operation[] | null;
+  deprecated?: boolean | null;
+  parameters?: Parameter[] | null;
+
   constructor(name: string, url: string, options: ResourceOptions = {}) {
     this.name = name;
     this.url = url;
-    assignSealed(this, options);
+    Object.assign(this, options);
   }
 }

src/core/index.ts

@@ -3,3 +3,4 @@ export * from "./Field.js";
 export * from "./Operation.js";
 export * from "./Parameter.js";
 export * from "./Resource.js";
+export * from "./types.js";

src/core/utils/assignSealed.ts

@@ -5,8 +5,8 @@ import { humanize } from "inflection";
  * The keys of the object are the humanized versions of the enum values,
  * and the values are the original enum values.
  *
- * @param enumArray - An array of enum values.
- * @returns An object mapping humanized enum names to their original values, or null if the input is empty.
+ * @param {any[] | undefined} enumArray - An array of enum values.
+ * @returns {Record<string, string | number> | null} An object mapping humanized enum names to their original values, or null if the input is empty.
  */
 export function buildEnumObject(
   enumArray: any[] | undefined,

src/core/utils/buildEnumObject.ts

@@ -7,9 +7,9 @@ import type { FieldType } from "../Field.js";
  * If a format is provided, it will map certain formats (e.g., "int32", "int64") to "integer".
  * Otherwise, it will camelize the format string. If no format is provided, it returns the OpenAPI type.
  *
- * @param openApiType - The OpenAPI type string.
- * @param format - An optional format string.
- * @returns The mapped FieldType.
+ * @param {string} openApiType - The OpenAPI type string.
+ * @param {string} [format] - An optional format string.
+ * @returns {FieldType} The mapped FieldType.
  */
 export function getType(openApiType: string, format?: string): FieldType {
   if (format) {