ajsc 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,145 @@
+# ajsc - Another JSON Schema Parser
+
+**ajsc** is an npm package that transforms JSON Schema definitions into an intermediate representation (IR) called `IRNode`. This intermediate form is designed to be consumed by language-specific converters—such as the built-in [TypeScript converter](#typescriptconverter)—or by any custom converter you create for languages like Kotlin or Swift. This library streamlines the process of converting API JSON Schema definitions into strong-typed code representations, ensuring consistency between your API contracts and client implementations.
+
+---
+
+## Features
+
+- **Comprehensive Schema Parsing:**  
+  Convert JSON Schema types including strings, numbers, booleans, nulls, literals, enums, unions, intersections, arrays, and objects into a unified IR.
+
+- **Intermediate Representation (`IRNode`):**  
+  The `IRNode` provides a standard structure that captures type, constraints, and path information. This representation is ideal for further transformation into various target languages.
+
+- **Plugin-Based Architecture:**  
+  Use the provided language plugin (currently, a [TypeScript converter](#typescriptconverter)) or write your own converter to support additional languages such as Kotlin or Swift.
+
+- **$defs and References Handling:**  
+  Resolve JSON Schema definitions (`$defs`) and references (`$ref`) seamlessly, ensuring reusable schema components are properly processed.
+
+- **Unique Signature Tracking:**  
+  For objects and arrays, the library tracks unique signatures to avoid duplicate type definitions when converting to code.
+
+---
+
+## Installation
+
+Install **ajsc** via npm:
+
+```bash
+npm install ajsc
+```
+
+## Usage
+### Basic Conversion to IRNode
+The primary function of ajsc is to convert a JSON Schema into an IRNode. Here’s an example of converting a simple JSON Schema that defines a string type:
+
+```javascript
+import { JSONSchemaConverter } from "ajsc";
+
+const schema = { type: "string" };
+const converter = new JSONSchemaConverter(schema);
+
+console.log(converter.irNode);
+// Output:
+// {
+//   type: "string",
+//   constraints: {},
+//   path: "",
+// }
+Converting Complex Schemas
+You can also convert more complex schemas including objects, arrays, unions, intersections, and even schemas with $defs:
+
+javascript
+Copy
+import { JSONSchemaConverter } from "ajsc";
+
+const complexSchema = {
+$defs: {
+Person: {
+type: "object",
+properties: {
+name: { type: "string" },
+age: { type: "number" },
+},
+required: ["name"],
+},
+},
+type: "object",
+properties: {
+person: { $ref: "#/$defs/Person" },
+},
+};
+
+const converter = new JSONSchemaConverter(complexSchema);
+console.log(converter.irNode);
+```
+
+## API Reference
+### JSONSchemaConverter
+- Constructor:
+ `new JSONSchemaConverter(schema: object)`
+- Properties:
+  - irNode: The resulting intermediate representation of the JSON Schema. 
+- Supported Schema Types:
+  - Primitive Types: string, number, boolean, null 
+  - Literals: Using the const keyword. 
+  - Enums: Using the enum property. 
+  - Unions: When type is an array (e.g., ["string", "number"]). 
+  - Intersections: Using allOf to combine multiple schemas. 
+  - Arrays: With type: "array" and an items schema. 
+  - Objects: With type: "object" and a properties definition.
+  - $defs and $ref: For defining and referencing reusable schema parts.
+
+### TypescriptConverter
+
+The package includes a TypeScript language plugin that converts the IRNode into TypeScript type definitions.
+
+- Constructor:
+`new TypescriptConverter(schema: object, options?: { inlineTypes?: boolean })`
+- Properties:
+  - code: A string containing the generated TypeScript code.
+  
+Usage Example:
+
+```javascript
+import { TypescriptConverter } from "ajsc";
+
+const schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "number" },
+    contacts: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          email: { type: "string" },
+        },
+        required: ["email"],
+      },
+    },
+    profile: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+      },
+      required: ["email"],
+    },
+  },
+  required: ["name", "age"],
+};
+
+const tsConverter = new TypescriptConverter(schema, { inlineTypes: true });
+console.log(tsConverter.code);
+
+// Expected output (formatted):
+// {
+//   name: string;
+//   age: number;
+//   contacts?: Array<{ email: string; }>;
+//   profile?: { email: string; };
+// }
+```

package/dist/JSONSchemaConverter.d.ts

@@ -0,0 +1,65 @@
+import { JSONSchema7Definition } from "json-schema";
+import { ConverterOptions, IRNode, SignatureOccurrences } from "./types.js";
+/**
+ * JSONSchemaConverter converts a JSON Schema (Draft‑07) into an
+ * intermediate representation (IR) that can later be transformed
+ * into target language code via a language plugin.
+ *
+ * This implementation now supports internal definitions via both
+ * "$defs" and "definitions", and resolves local "$ref" pointers.
+ */
+export declare class JSONSchemaConverter {
+    private opts?;
+    private ir;
+    private rootSchema;
+    private signatureOccurrences;
+    get irNode(): IRNode;
+    get signatureOccurrencesMap(): SignatureOccurrences;
+    constructor(schema: JSONSchema7Definition, opts?: ConverterOptions | undefined);
+    private calcObjSignatureOccurrences;
+    /**
+     * Recursively converts a JSON Schema definition into an IRNode.
+     *
+     * This method now handles $ref resolution (using the root schema),
+     * combinators (oneOf, anyOf, allOf), as well as enums, const, objects,
+     * arrays, and primitives.
+     */
+    private convertSchema;
+    /**
+     * Converts a JSON Schema definition to target code using the provided language plugin.
+     */
+    convertToIRSchema(schema: JSONSchema7Definition): IRNode;
+    private validateSchema;
+    /**
+     * A placeholder for reference resolution. In a more advanced implementation,
+     * this method might inline external references or perform more complex processing.
+     * ie: fetching a remote/url $def
+     */
+    private resolveReferences;
+    private convertToIR;
+    private getNameFromPath;
+    private getNextObjectSequence;
+    private getParentNameFromPath;
+    /**
+     * Generates a unique signature for a schema.
+     * Uses a stable JSON.stringify that sorts keys to ensure that
+     * semantically equivalent schemas produce the same string.
+     */
+    private getSchemaSignature;
+    private getTypeName;
+    /**
+     * Resolves a local $ref using the stored root schema.
+     *
+     * This method expects local references (starting with "#/") and uses a simple
+     * JSON Pointer resolution algorithm.
+     */
+    private resolveRef;
+    /**
+     * Resolves a JSON Pointer (RFC 6901) within the given document.
+     *
+     * @param pointer A JSON Pointer string (e.g., "#/definitions/Foo" or "#/$defs/Bar")
+     * @param document The root document object.
+     */
+    private resolvePointer;
+    private simpleHash;
+}

package/dist/JSONSchemaConverter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/TypescriptBaseConverter.d.ts

@@ -0,0 +1,56 @@
+import { IRNode, SignatureOccurrenceValue } from "./types.js";
+export type RefTypeName = string;
+export type RefTypes = [
+    SignatureOccurrenceValue["signature"],
+    RefTypeName,
+    {
+        code: string;
+    }
+][];
+export declare class TypescriptBaseConverter {
+    /**
+     * Recursively generates a TypeScript type string for the given IR node.
+     *
+     * @param ir - The IR node to convert.
+     * @returns A string representing the TypeScript type.
+     */
+    protected generateType(ir: IRNode, utils: {
+        getReferencedType(ir: IRNode): string | undefined;
+    }): string;
+    /**
+     * Generates a TypeScript object type (as an inline type literal) from the given IR node.
+     *
+     * @param ir - The IR node of type "object".
+     * @returns A string representing the object type.
+     */
+    protected generateObjectType(ir: IRNode, utils: {
+        getReferencedType(ir: IRNode): string | undefined;
+    }): string;
+    protected isValidIdentifier(name: string): boolean;
+    /**
+     * Parses a list of dot-separated paths into an array of string arrays.
+     * Removes any "0" character segments.
+     *
+     * @param list
+     * @protected
+     */
+    protected parsePaths(list: string[]): string[][];
+    /**
+     * Returns the longest common prefix (sequence) among an array of string arrays.
+     * @param paths - An array of string arrays.
+     * @returns An array representing the common sequence.
+     *
+     * @example
+     *  const arrays = [
+     *      ["organizations", "migration", "step", "create_regions"],
+     *      ["organizations", "migration", "step", "create_location_groups"],
+     *      ["organizations", "migration", "step", "create_locations"],
+     *      ["organizations", "migration", "step", "create_locations_bolos"],
+     *   ];
+     *
+     *   console.log(commonSequence(arrays)); // Output: ["organizations", "migration", "step"]
+     *
+     */
+    protected commonSequence(paths: string[][]): string[];
+    protected makeTypeReferenceName(signatureOccurrences: SignatureOccurrenceValue["occurrences"]): string;
+}

package/dist/TypescriptConverter.d.ts

@@ -0,0 +1,21 @@
+import { IRNode, LanguagePlugin } from "./types.js";
+import { TypescriptBaseConverter } from "./TypescriptBaseConverter.js";
+import { JSONSchema7Definition } from "json-schema";
+/**
+ * A TypeScript language converter plugin.
+ */
+export declare class TypescriptConverter extends TypescriptBaseConverter implements LanguagePlugin {
+    readonly language = "typescript";
+    private ir;
+    private refTypes;
+    readonly code: string;
+    constructor(schema: JSONSchema7Definition, opts?: {
+        /**
+         * If true, referenced types will not be created for objects and instead
+         * the object type will be inlined.
+         */
+        inlineTypes?: boolean;
+    });
+    private getUniqueRefTypeName;
+    protected getReferencedType(ir: IRNode): string | undefined;
+}

package/dist/TypescriptConverter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/TypescriptProcedureConverter.d.ts

@@ -0,0 +1,20 @@
+import { IRNode } from "./types.js";
+import { JSONSchema7Definition } from "json-schema";
+import { TypescriptBaseConverter } from "./TypescriptBaseConverter.js";
+/**
+ * A TypeScript language converter plugin that implements namespace scoping.
+ *
+ * Referenced/Shared typings are moved to the top level of the namespace scope
+ * that is created for each IR node.
+ */
+export declare class TypescriptProcedureConverter extends TypescriptBaseConverter {
+    private ir;
+    private refTypes;
+    readonly code: string;
+    constructor(scopeName: string, rpcJsonSchemas: {
+        args: JSONSchema7Definition;
+        data: JSONSchema7Definition;
+    });
+    private getUniqueRefTypeName;
+    protected getReferencedType(ir: IRNode): string | undefined;
+}

package/dist/TypescriptProceduresConverter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './JSONSchemaConverter.js';
+export * from './TypescriptBaseConverter.js';
+export * from './TypescriptConverter.js';
+export * from './TypescriptProcedureConverter.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './JSONSchemaConverter.js';
+export * from './TypescriptBaseConverter.js';
+export * from './TypescriptConverter.js';
+export * from './TypescriptProcedureConverter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mCAAmC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type IRType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | "enum" | "union" | "intersection" | "literal";
+export interface IRNode {
+    signature?: string;
+    /**
+     * The base type of the IR node.
+     */
+    type: IRType;
+    /**
+     * Optional name for the node (useful for objects, enums, etc.).
+     */
+    name?: string;
+    /**
+     * Dot notation path to the node in a runtime object.
+     * For example, "user.profile.name".
+     */
+    path: string;
+    /**
+     * Indicates whether this property/node is required.
+     * For object properties, this can be derived from the JSON Schema 'required' array.
+     */
+    required?: boolean;
+    /**
+     * For object types: a mapping of property names to their IR node definitions.
+     */
+    properties?: {
+        [key: string]: IRNode;
+    };
+    /**
+     * For array types: the IR node representing the type of items in the array.
+     */
+    items?: IRNode;
+    /**
+     * For enum types: a list of allowed literal values.
+     */
+    values?: any[];
+    /**
+     * For union or intersection types: an array of candidate IR nodes.
+     * Note: This is used regardless of whether the union originated from a 'oneOf' or an 'anyOf'.
+     */
+    options?: IRNode[];
+    /**
+     * Additional constraints such as minimum, maximum, pattern, etc.
+     */
+    constraints?: {
+        [key: string]: any;
+        combinator?: "oneOf" | "anyOf";
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        maximum?: number;
+        minimum?: number;
+        value?: any;
+    };
+}
+export type SignatureOccurrenceValue = {
+    occurrences: {
+        node: IRNode;
+        nodePath: string;
+        count: number;
+    }[];
+    signature: string;
+    total: number;
+};
+export type SignatureOccurrences = Map<string, SignatureOccurrenceValue>;
+export interface Context {
+    signatureOccurrences: SignatureOccurrences;
+}
+export interface LanguagePlugin {
+    /**
+     * The name of the language this plugin converts to (e.g., "typescript", "java", "python").
+     */
+    language: string;
+}
+export interface ConverterOptions {
+    validateSchema?: boolean;
+    transform?: (ir: IRNode) => IRNode;
+}

package/dist/utils/path-utils.d.ts

@@ -0,0 +1,26 @@
+export declare const PathUtils: {
+    /**
+     * Parses a list of dot-separated paths into an array of string arrays.
+     * Removes any "0" character segments.
+     *
+     * @param list
+     * @protected
+     */
+    parsePaths: (list: string[]) => string[][];
+    parsePath: (path: string) => string[];
+    /**
+     * Returns the last `count` common elements (shared path) among all given path arrays,
+     * comparing from the end (i.e. common suffix).
+     *
+     * @param paths - An array of string arrays (paths) to compare.
+     * @param count - The number of common elements (starting from the end) to return.
+     * @returns An array containing the shared path elements in original order.
+     */
+    commonSequenceReversed: (paths: string[][], count?: number) => string[];
+    /**
+     * Returns the longest common prefix (sequence) among an array of string arrays.
+     * @param paths - An array of string arrays.
+     * @returns An array representing the common sequence.
+     */
+    commonSequence: (paths: string[][]) => string[];
+};

package/dist/utils/path-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/to-pascal-case.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Converts a string to PascalCase.
+ * Splits on whitespace, hyphens, or underscores.
+ */
+export declare function toPascalCase(str: string): string;

package/package.json

@@ -1,26 +1,15 @@
 {
   "name": "ajsc",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Another Json-Schema Converter",
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "test": "vitest --run"
   },
-  "exports": {
-    "./JSONSchemaConverter": {
-      "types": "./dist/JSONSchemaConverter.d.ts",
-      "default": "./dist/JSONSchemaConverter.js"
-    },
-    "./TypescriptConverter": {
-      "types": "./dist/TypescriptConverter.d.ts",
-      "default": "./dist/TypescriptConverter.js"
-    },
-    "./TypescriptProcedureConverter": {
-      "types": "./dist/TypescriptProcedureConverter.d.ts",
-      "default": "./dist/TypescriptProcedureConverter.js"
-    }
-  },
   "keywords": [
     "json-schema",
     "converter",

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './JSONSchemaConverter.js';
+export * from './TypescriptBaseConverter.js';
+export * from './TypescriptConverter.js';
+export * from './TypescriptProcedureConverter.js';