@ng-org/shex-orm 0.1.2

package/src/build.ts

@@ -0,0 +1,106 @@
+// Copyright (c) 2025 Laurin Weger, Par le Peuple, NextGraph.org developers
+// All rights reserved.
+// Copyright (c) 2023 Jackson Morgan
+// Licensed under the Apache License, Version 2.0
+// <LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0>
+// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+// at your option. All files in the project carrying such
+// notice may not be copied, modified, or distributed except
+// according to those terms.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+import fs from "fs-extra";
+import path from "path";
+import type { Schema } from "./ShexJTypes.ts";
+import parser from "@shexjs/parser";
+import { shexJConverter } from "./schema-converter/converter.ts";
+import { renderFile } from "ejs";
+import prettier from "prettier";
+import loading from "loading-cli";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { forAllShapes } from "./util/forAllShapes.ts";
+import annotateReadablePredicates from "./schema-converter/util/annotateReadablePredicates.ts";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface BuildOptions {
+    input: string;
+    output: string;
+    baseIRI?: string;
+}
+
+export async function build({
+    input: inputFile,
+    output: outputFile,
+    baseIRI = "https://nextgraph.org/shapes#",
+}: BuildOptions) {
+    const load = loading("Preparing Environment");
+    load.start();
+    // Prepare new folder by clearing/and/or creating it
+    if (fs.existsSync(outputFile)) {
+        await fs.promises.rm(outputFile, { recursive: true });
+    }
+    await fs.promises.mkdir(outputFile);
+
+    const fileTemplates: string[] = [];
+
+    // Pre-annotate schema with readablePredicate to unify naming across outputs
+    fileTemplates.push("schema", "typings", "shapeTypes");
+
+    load.text = "Generating Schema Documents";
+    await forAllShapes(inputFile, async (fileName, shexC) => {
+        // Convert to ShexJ
+        let schema: Schema;
+        try {
+            // Prase Shex schema to JSON.
+            // TODO: Do we need the base IRI?
+            //  @ts-ignore ...
+            schema = parser.construct(baseIRI).parse(shexC);
+        } catch (err) {
+            const errMessage =
+                err instanceof Error
+                    ? err.message
+                    : typeof err === "string"
+                      ? err
+                      : "Unknown Error";
+            console.error(`Error processing ${fileName}: ${errMessage}`);
+            return;
+        }
+
+        // Add readable predicates to schema as the single source of truth.
+        //  @ts-ignore ...
+        annotateReadablePredicates(schema);
+
+        const [typings, compactSchema] = await shexJConverter(schema);
+
+        await Promise.all(
+            fileTemplates.map(async (templateName) => {
+                const finalContent = await renderFile(
+                    path.join(
+                        __dirname,
+                        "schema-converter",
+                        "templates",
+                        `${templateName}.ejs`
+                    ),
+                    {
+                        typings: typings.typings,
+                        fileName,
+                        schema: JSON.stringify(schema, null, 2),
+                        compactSchema: JSON.stringify(compactSchema, null, 2),
+                    }
+                );
+                await fs.promises.writeFile(
+                    path.join(outputFile, `${fileName}.${templateName}.ts`),
+                    await prettier.format(finalContent, {
+                        parser: "typescript",
+                    })
+                );
+            })
+        );
+    });
+
+    load.stop();
+}

package/src/cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import { build } from "./build.ts";
+
+program
+    .name("NG-ORM")
+    .description("CLI to some JavaScript string utilities")
+    .version("0.1.0");
+
+program
+    .command("build")
+    .description("Build contents of a shex folder into Shape Types")
+    .option("-i, --input <inputPath>", "Provide the input path", "./.shapes")
+    .option("-o, --output <outputPath>", "Provide the output path", "./.orm")
+    .option(
+        "-b, --baseIRI <baseIri>",
+        "The base IRI for anonymous shapes",
+        "https://nextgraph.org/shapes#"
+    )
+    .action(build);
+
+program.parse();

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./types.ts";

package/src/schema-converter/__tests__/typingTransformer.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import annotateReadablePredicates from "../util/annotateReadablePredicates.ts";
+import { shexJConverter } from "../converter.ts";
+
+const TYPE_IRI = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+function buildSchema() {
+    return {
+        type: "Schema",
+        shapes: [
+            {
+                type: "ShapeDecl",
+                id: "http://example.org/Expense",
+                shapeExpr: {
+                    type: "Shape",
+                    expression: {
+                        type: "EachOf",
+                        expressions: [
+                            {
+                                type: "TripleConstraint",
+                                predicate: TYPE_IRI,
+                                valueExpr: {
+                                    type: "NodeConstraint",
+                                    values: [
+                                        {
+                                            value: "http://example.org/Expense",
+                                        },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                },
+            },
+            {
+                type: "ShapeDecl",
+                id: "http://example.org/ExpenseCategory",
+                shapeExpr: {
+                    type: "Shape",
+                    extra: [TYPE_IRI],
+                    expression: {
+                        type: "EachOf",
+                        expressions: [
+                            {
+                                type: "TripleConstraint",
+                                predicate: TYPE_IRI,
+                                valueExpr: {
+                                    type: "NodeConstraint",
+                                    values: [
+                                        {
+                                            value: "http://example.org/ExpenseCategory",
+                                        },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                },
+            },
+        ],
+    };
+}
+
+async function buildTypingsText(): Promise<string> {
+    const schema = buildSchema();
+    annotateReadablePredicates(schema as any);
+    const [typings] = await shexJConverter(schema as any);
+    return typings.typingsString;
+}
+
+describe("ShexJTypingTransformer", () => {
+    it("emits literal unions for rdf:type constraints", async () => {
+        const typings = await buildTypingsText();
+        expect(typings).toMatch(
+            /interface Expense[\s\S]*?"@type": "http:\/\/example\.org\/Expense";/
+        );
+    });
+
+    it("treats EXTRA rdf:type predicates as plural", async () => {
+        const typings = await buildTypingsText();
+        expect(typings).toMatch(
+            /interface ExpenseCategory[\s\S]*?"@type": Set<"http:\/\/example\.org\/ExpenseCategory" \|[\s]*\(?string[\s]*&[\s]*\{[\s]*\}\)?>;/
+        );
+    });
+});

package/src/schema-converter/converter.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2025 Laurin Weger, Par le Peuple, NextGraph.org developers
+// All rights reserved.
+// Copyright (c) 2023 Jackson Morgan
+// Licensed under the Apache License, Version 2.0
+// <LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0>
+// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+// at your option. All files in the project carrying such
+// notice may not be copied, modified, or distributed except
+// according to those terms.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+import type { Schema } from "@ldo/traverser-shexj";
+import { jsonld2graphobject } from "jsonld2graphobject";
+import * as dom from "dts-dom";
+import {
+    ShexJTypingTransformerCompact,
+    additionalCompactEnumAliases,
+} from "./transformers/ShexJTypingTransformer.ts";
+import { ShexJSchemaTransformerCompact } from "./transformers/ShexJSchemaTransformer.ts";
+import type { Schema as ShapeSchema, Shape } from "../types.ts";
+
+export interface TypingReturn {
+    typingsString: string;
+    typings: {
+        typingString: string;
+        dts: dom.TopLevelDeclaration;
+    }[];
+}
+
+export async function shexJConverter(
+    shexj: Schema
+): Promise<[TypingReturn, ShapeSchema]> {
+    // Prepare processed schema (names still rely on context visitor)
+    const processedShexj: Schema = (await jsonld2graphobject(
+        {
+            ...shexj,
+            "@id": "SCHEMA",
+            "@context": "http://www.w3.org/ns/shex.jsonld",
+        },
+        "SCHEMA"
+    )) as unknown as Schema;
+
+    additionalCompactEnumAliases.clear();
+    const declarations = await ShexJTypingTransformerCompact.transform(
+        processedShexj,
+        "Schema",
+        null
+    );
+
+    const compactSchemaShapesUnflattened =
+        await ShexJSchemaTransformerCompact.transform(
+            processedShexj,
+            "Schema",
+            null
+        );
+    const compactSchema = flattenSchema(compactSchemaShapesUnflattened);
+
+    // Append only enum aliases (no interface Id aliases in compact format now)
+    const hasName = (d: unknown): d is { name: string } =>
+        typeof (d as { name?: unknown }).name === "string";
+    additionalCompactEnumAliases.forEach((alias) => {
+        const exists = declarations.some((d) => hasName(d) && d.name === alias);
+        if (!exists)
+            declarations.push(
+                dom.create.alias(alias, dom.create.namedTypeReference("IRI"))
+            );
+    });
+
+    const typings = declarations.map((declaration) => ({
+        typingString: dom
+            .emit(declaration, {
+                rootFlags: dom.ContextFlags.InAmbientNamespace,
+            })
+            .replace(/\r\n/g, "\n"),
+        dts: declaration,
+    }));
+    const header = `export type IRI = string;\n\n`;
+    const typingsString =
+        header + typings.map((t) => `export ${t.typingString}`).join("");
+
+    return [{ typingsString, typings }, compactSchema];
+}
+
+/** Shapes may be nested. Put all to their root and give nested ones ids. */
+function flattenSchema(shapes: Shape[]): ShapeSchema {
+    let schema: ShapeSchema = {};
+
+    for (const shape of shapes) {
+        schema[shape.iri] = shape;
+
+        // Find nested, unflattened (i.e. anonymous) schemas in predicates' dataTypes.
+        for (const pred of shape.predicates) {
+            for (let i = 0; i < pred.dataTypes.length; i++) {
+                const dt = pred.dataTypes[i];
+                if (
+                    dt.valType === "shape" &&
+                    typeof dt.shape === "object" &&
+                    dt.shape !== null
+                ) {
+                    // create a deterministic id for the nested shape; include index if multiple shape entries exist
+                    const shapeCount = pred.dataTypes.filter(
+                        (d) => d.valType === "shape"
+                    ).length;
+                    const newId =
+                        shape.iri +
+                        "||" +
+                        pred.iri +
+                        (shapeCount > 1 ? `||${i}` : "");
+
+                    // Recurse
+                    const flattened = flattenSchema([
+                        {
+                            ...(dt.shape as Shape),
+                            iri: newId,
+                        },
+                    ]);
+                    // Replace the nested schema with its new id.
+                    dt.shape = newId;
+
+                    schema = { ...schema, ...flattened };
+                }
+            }
+        }
+        // Flatten / Recurse
+    }
+
+    return schema;
+}

package/src/schema-converter/templates/schema.ejs

@@ -0,0 +1,8 @@
+import type { Schema } from "@ng-org/shex-orm";
+
+/**
+* =============================================================================
+* <%- fileName %>Schema: Schema for <%- fileName %>
+                * =============================================================================
+                */
+                export const <%- fileName %>Schema: Schema = <%- compactSchema %>;

package/src/schema-converter/templates/shapeTypes.ejs

@@ -0,0 +1,14 @@
+import type { ShapeType } from "@ng-org/shex-orm";
+import { <%- fileName %>Schema } from "./<%- fileName %>.schema";
+    import type {
+    <% typings.forEach((typing)=> { if (!/Id$/.test(typing.dts.name)) { -%>
+      <%- typing.dts.name %>,
+        <% } }); -%>} from "./<%- fileName %>.typings";
+
+            // ShapeTypes for <%- fileName %>
+              <% typings.forEach((typing)=> { if (!/Id$/.test(typing.dts.name)) { -%>
+                export const <%- typing.dts.name %>ShapeType: ShapeType<<%- typing.dts.name %>> = {
+                    schema: <%- fileName %>Schema,
+                      shape: "<%- typing.dts.shapeId %>",
+                        };
+                        <% } }); -%>

package/src/schema-converter/templates/typings.ejs

@@ -0,0 +1,14 @@
+export type IRI = string;
+
+/**
+* =============================================================================
+* Typescript Typings for <%- fileName %>
+  * =============================================================================
+  */
+
+  <% typings.forEach((typing)=> { -%>
+    /**
+    * <%- typing.dts.name %> Type
+      */
+      export <%- typing.typingString -%>
+        <% }); -%>

package/src/schema-converter/transformers/ShexJSchemaTransformer.ts

@@ -0,0 +1,284 @@
+// Copyright (c) 2025 Laurin Weger, Par le Peuple, NextGraph.org developers
+// All rights reserved.
+// Licensed under the Apache License, Version 2.0
+// <LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0>
+// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+// at your option. All files in the project carrying such
+// notice may not be copied, modified, or distributed except
+// according to those terms.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+import ShexJTraverser from "@ldo/traverser-shexj";
+import type { Predicate, DataType, Shape } from "../../types.ts";
+import type { ObjectLiteral } from "../../ShexJTypes.ts";
+
+const rdfDataTypeToBasic = (dataType: string) => {
+    switch (dataType) {
+        case "http://www.w3.org/2001/XMLSchema#string":
+        case "http://www.w3.org/2001/XMLSchema#ENTITIES":
+        case "http://www.w3.org/2001/XMLSchema#ENTITY":
+        case "http://www.w3.org/2001/XMLSchema#ID":
+        case "http://www.w3.org/2001/XMLSchema#IDREF":
+        case "http://www.w3.org/2001/XMLSchema#IDREFS":
+        case "http://www.w3.org/2001/XMLSchema#language":
+        case "http://www.w3.org/2001/XMLSchema#Name":
+        case "http://www.w3.org/2001/XMLSchema#NCName":
+        case "http://www.w3.org/2001/XMLSchema#NMTOKEN":
+        case "http://www.w3.org/2001/XMLSchema#NMTOKENS":
+        case "http://www.w3.org/2001/XMLSchema#normalizedString":
+        case "http://www.w3.org/2001/XMLSchema#QName":
+        case "http://www.w3.org/2001/XMLSchema#token":
+            return "string";
+        case "http://www.w3.org/2001/XMLSchema#date":
+        case "http://www.w3.org/2001/XMLSchema#dateTime":
+        case "http://www.w3.org/2001/XMLSchema#duration":
+        case "http://www.w3.org/2001/XMLSchema#gDay":
+        case "http://www.w3.org/2001/XMLSchema#gMonth":
+        case "http://www.w3.org/2001/XMLSchema#gMonthDay":
+        case "http://www.w3.org/2001/XMLSchema#gYear":
+        case "http://www.w3.org/2001/XMLSchema#gYearMonth":
+        case "http://www.w3.org/2001/XMLSchema#time":
+            return "string";
+        case "http://www.w3.org/2001/XMLSchema#byte":
+        case "http://www.w3.org/2001/XMLSchema#decimal":
+        case "http://www.w3.org/2001/XMLSchema#double":
+        case "http://www.w3.org/2001/XMLSchema#float":
+        case "http://www.w3.org/2001/XMLSchema#int":
+        case "http://www.w3.org/2001/XMLSchema#integer":
+        case "http://www.w3.org/2001/XMLSchema#long":
+        case "http://www.w3.org/2001/XMLSchema#negativeInteger":
+        case "http://www.w3.org/2001/XMLSchema#nonNegativeInteger":
+        case "http://www.w3.org/2001/XMLSchema#nonPositiveInteger":
+        case "http://www.w3.org/2001/XMLSchema#positiveInteger":
+        case "http://www.w3.org/2001/XMLSchema#short":
+        case "http://www.w3.org/2001/XMLSchema#unsignedLong":
+        case "http://www.w3.org/2001/XMLSchema#unsignedInt":
+        case "http://www.w3.org/2001/XMLSchema#unsignedShort":
+        case "http://www.w3.org/2001/XMLSchema#unsignedByte":
+            return "number";
+        case "http://www.w3.org/2001/XMLSchema#boolean":
+            return "boolean";
+        case "http://www.w3.org/2001/XMLSchema#hexBinary":
+            return "string";
+        case "http://www.w3.org/2001/XMLSchema#anyURI":
+            return "iri";
+        default:
+            return "string";
+    }
+};
+
+export const ShexJSchemaTransformerCompact = ShexJTraverser.createTransformer<
+    {
+        Schema: { return: Shape[] };
+        ShapeDecl: { return: Shape };
+        Shape: { return: Shape };
+        EachOf: { return: Shape };
+        TripleConstraint: { return: Predicate };
+        NodeConstraint: { return: DataType };
+        ShapeOr: { return: DataType[] };
+        ShapeAnd: { return: never };
+        ShapeNot: { return: never };
+        ShapeExternal: { return: never };
+    },
+    null
+>({
+    Schema: {
+        transformer: async (_schema, getTransformedChildren) => {
+            const transformedChildren = await getTransformedChildren();
+
+            return transformedChildren.shapes || [];
+        },
+    },
+
+    ShapeDecl: {
+        transformer: async (shapeDecl, getTransformedChildren) => {
+            const schema = await getTransformedChildren();
+            const shape = schema.shapeExpr as Shape;
+
+            return { ...shape, iri: shapeDecl.id } as Shape;
+        },
+    },
+
+    Shape: {
+        transformer: async (_shape, getTransformedChildren) => {
+            // TODO: We don't handles those
+            _shape.closed;
+
+            const transformedChildren = await getTransformedChildren();
+            const compactShape = transformedChildren.expression as Shape;
+
+            for (const extra of _shape.extra || []) {
+                const extraPredicate = compactShape.predicates.find(
+                    (p) => p.iri === extra
+                );
+                if (extraPredicate) extraPredicate.extra = true;
+            }
+
+            return compactShape;
+        },
+    },
+
+    // EachOf contains the `expressions` array of properties (TripleConstraint)
+    EachOf: {
+        transformer: async (eachOf, getTransformedChildren) => {
+            const transformedChildren = await getTransformedChildren();
+
+            return {
+                iri: "",
+                predicates: transformedChildren.expressions.map(
+                    // We disregard cases where properties are referenced (strings)
+                    // or where they consist of Unions or Intersections (not supported).
+                    (expr) => expr as Predicate
+                ),
+            };
+        },
+    },
+
+    TripleConstraint: {
+        transformer: async (
+            tripleConstraint,
+            getTransformedChildren,
+            _setReturnPointer
+        ) => {
+            const transformedChildren = await getTransformedChildren();
+
+            const commonProperties = {
+                maxCardinality: tripleConstraint.max ?? 1,
+                minCardinality: tripleConstraint.min ?? 1,
+                iri: tripleConstraint.predicate,
+                // @ts-expect-error The ldo library does not have our modded readablePredicate property.
+                readablePredicate: tripleConstraint.readablePredicate,
+            } satisfies Partial<Predicate>;
+            // Make property based on object type which is either a parsed schema, literal or type.
+            if (typeof transformedChildren.valueExpr === "string") {
+                // Reference to nested object
+                return {
+                    dataTypes: [
+                        {
+                            valType: "shape",
+                            shape: transformedChildren.valueExpr,
+                        },
+                    ],
+                    ...commonProperties,
+                };
+            } else if (
+                transformedChildren.valueExpr &&
+                (transformedChildren.valueExpr as Shape).predicates
+            ) {
+                // Nested object
+                return {
+                    dataTypes: [
+                        {
+                            valType: "shape",
+                            shape: transformedChildren.valueExpr as Shape,
+                        },
+                    ],
+                    ...commonProperties,
+                };
+            } else if (Array.isArray(transformedChildren.valueExpr)) {
+                return {
+                    dataTypes: transformedChildren.valueExpr, // DataType[]
+                    ...commonProperties,
+                };
+            } else {
+                // type or literal
+                const nodeConstraint =
+                    transformedChildren.valueExpr as DataType;
+                return {
+                    dataTypes: [
+                        {
+                            valType: nodeConstraint.valType,
+                            literals: nodeConstraint.literals,
+                        },
+                    ],
+                    ...commonProperties,
+                };
+            }
+        },
+    },
+
+    NodeConstraint: {
+        transformer: async (nodeConstraint) => {
+            if (nodeConstraint.datatype) {
+                return {
+                    valType: rdfDataTypeToBasic(nodeConstraint.datatype),
+                };
+            }
+            if (nodeConstraint.nodeKind) {
+                // Something reference-like.
+                return { valType: "iri" };
+            }
+            if (nodeConstraint.values) {
+                return {
+                    valType: "literal",
+                    literals: nodeConstraint.values.map(
+                        // TODO: We do not convert them to number or boolean or lang tag.
+                        // And we don't have an annotation of the literal's type.
+                        (valueRecord) => {
+                            // If valueRecord is a string (IRIREF), return it directly
+                            if (typeof valueRecord === "string") {
+                                return valueRecord;
+                            }
+                            // Handle ObjectLiteral (has .value property)
+                            if ("value" in valueRecord) {
+                                return valueRecord.value;
+                            }
+                            // Handle other types with .id property (if any)
+                            if ("id" in valueRecord) {
+                                return (valueRecord as any).id;
+                            }
+                            // Handle Language type (has .languageTag)
+                            if ("languageTag" in valueRecord) {
+                                return valueRecord.languageTag;
+                            }
+                            // Handle stem-based types (IriStem, LiteralStem, LanguageStem)
+                            if ("stem" in valueRecord) {
+                                return valueRecord.stem as string;
+                            }
+                            // Fallback - should not happen in well-formed ShEx
+                            return undefined;
+                        }
+                    ),
+                };
+            }
+
+            // Maybe we should throw instead...
+            throw {
+                error: new Error("Could not parse Node Constraint"),
+                nodeConstraint,
+            };
+        },
+    },
+
+    // Transformer from ShapeOr
+    ShapeOr: {
+        transformer: async (shapeOr, getTransformedChildren) => {
+            const { shapeExprs } = await getTransformedChildren();
+            // Either a shape IRI, a nested shape or a node CompactSchemaValue (node constraint).
+            return (
+                Array.isArray(shapeExprs) ? shapeExprs : [shapeExprs]
+            ) as DataType[];
+        },
+    },
+
+    // Transformer from ShapeAnd
+    ShapeAnd: {
+        transformer: async () => {
+            throw new Error("ShapeAnd not supported (compact)");
+        },
+    },
+
+    // Transformer from ShapeNot - not supported.
+    ShapeNot: {
+        transformer: async () => {
+            throw new Error("ShapeNot not supported (compact)");
+        },
+    },
+
+    // Transformer from ShapeExternal - not supported.
+    ShapeExternal: {
+        transformer: async () => {
+            throw new Error("ShapeExternal not supported (compact)");
+        },
+    },
+});