@ng-org/shex-orm 0.1.2-alpha.4 → 0.1.2-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +46 -142
  2. package/dist/schema-converter/transformers/ShexJTypingTransformer.js +1 -1
  3. package/dist/types.d.ts +12 -2
  4. package/dist/types.d.ts.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # Schema Converter SHEX > TypeScript
2
2
 
3
- CLI tool to convert SHEX shapes to schemas and TypeScript definitions ("shape types") that can be used for creating ORM objects.
3
+ CLI tool to convert SHEX shapes to schemas and TypeScript definitions ("shape types") that can be used for creating graph ORM objects.
4
+
5
+ ## Reference documentation
6
+
7
+ [Reference documentation is available here on docs.nextgraph.org](https://docs.nextgraph.org/en/reference/shex-orm/).
4
8
 
5
9
  ## How to Use
6
10
 
@@ -16,7 +20,42 @@ Then run
16
20
  npx rdf-orm build --input ./src/shapes/shex --output ./src/shapes/orm
17
21
  ```
18
22
 
19
- The input directory needs to contain shex files with one or more shape definitions each.
23
+ The input directory needs to contain shex files with one or more shape definitions each, for example:
24
+
25
+ ```shex
26
+ PREFIX ex: <http://example.org/>
27
+ PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
28
+
29
+ ex:ExpenseShape {
30
+ a [ex:Person] ; # Required type <http://example.org/Person>
31
+ ex:name xsd:string ; # Required string
32
+ ex:email xsd:string * ; # Zero or more strings (set)
33
+ ex:height xsd:float ; # Required number
34
+ ex:age xsd:integer ; # Required integer
35
+ ex:friends IRI * ; # Set of IRIs
36
+ ex:isRecurring xsd:boolean ; # A boolean value
37
+ ex:address @ex:AddressShape ; # A nested object shape.
38
+ ex:paymentStatus [ex:Paid ex:Pending ex:Overdue] ; # Enum
39
+ }
40
+
41
+ # In the same or another file...
42
+ ex:AddressShape EXTRA a {
43
+ a [ ex:Address ] ;
44
+ ex:name xsd:string ;
45
+ }
46
+ ```
47
+
48
+ **SHEX Cardinality Reference**
49
+
50
+ | Syntax | Meaning | TypeScript Type |
51
+ | ------------------- | --------------------------- | ------------------------- |
52
+ | `prop xsd:string` | Required, exactly one | `string` |
53
+ | `prop xsd:string ?` | Optional, zero or one | `string \| undefined` |
54
+ | `prop xsd:string *` | Zero or more | `Set<string>` |
55
+ | `prop xsd:string +` | One or more | `Set<string>` (non-empty) |
56
+ | `prop IRI` | Reference to another object | `string` (IRI) |
57
+ | `@ex:PersonShape` | nested object | `Person` |
58
+
20
59
  The output directory will contain the typescript files with type definitions and the converted schema.
21
60
 
22
61
  You will then pass the shape type of a shape definition to the ng sdk:
@@ -26,12 +65,12 @@ import { useShape } from "@ng-org/orm/react";
26
65
  import { TestObjectShapeType } from "../shapes/orm/testShape.shapeTypes";
27
66
 
28
67
  export function TestComponent() {
29
- const testObjects = useShape(TestObjectShapeType);
68
+ const testObjects = useShape(TestObjectShapeType, {graphs: ["did:ng:i"]});
30
69
  ...
31
70
  }
32
71
  ```
33
72
 
34
- For an example, see the [multi-framework-signals example application](../examples/multi-framework-signals/README.md).
73
+ For an example, see the [expense-tracker-graph example application](https://git.nextgraph.org/NextGraph/expense-tracker-graph).
35
74
 
36
75
  ## Generated Output
37
76
 
@@ -39,149 +78,14 @@ For each SHEX file, the tool creates three TypeScript files:
39
78
 
40
79
  - A schema file like `person.schema.ts`
41
80
  - A typings file like `person.typings.ts`
42
- - A shape type file like `person.shapeTypes.ts` which contains a `ShapeType` that consists of the schema, the type, and the IRI of the main shape
81
+ - A shape type file like `person.shapeTypes.ts` which contains a `ShapeType` that consists of the schema, the type, and the IRI of the main shape. This is what you pass to the ORM.
43
82
 
44
83
  The transformers for converting SHEX to schema and typings files are based on `@ldo/traverser-shexj`.
45
84
 
46
- ### ShapeType File
47
-
48
- ```ts
49
- export const PersonShapeType: ShapeType<Person> = {
50
- schema: personSchema,
51
- shape: "http://example.org/PersonShape",
52
- };
53
- ```
54
-
55
- ### Schema File
56
-
57
- ```ts
58
- import type { Schema } from "@ng-org/shex-orm";
59
-
60
- export const personSchema: Schema = {
61
- "http://example.org/PersonShape": {
62
- iri: "http://example.org/PersonShape",
63
- predicates: [
64
- {
65
- dataTypes: [
66
- {
67
- valType: "literal",
68
- literals: ["http://example.org/Person"],
69
- },
70
- ],
71
- maxCardinality: -1,
72
- minCardinality: 1,
73
- iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
74
- readablePredicate: "@type",
75
- // `extra` here allows additional type values along with `http://example.org/Person`.
76
- extra: true,
77
- },
78
- {
79
- dataTypes: [{ valType: "string" }],
80
- maxCardinality: 1,
81
- minCardinality: 1,
82
- iri: "http://example.org/name",
83
- readablePredicate: "name",
84
- },
85
- {
86
- dataTypes: [{ valType: "string" }],
87
- maxCardinality: -1,
88
- minCardinality: 0,
89
- iri: "http://example.org/email",
90
- readablePredicate: "email",
91
- },
92
- {
93
- dataTypes: [
94
- {
95
- valType: "shape",
96
- shape: "http://example.org/PersonShape||http://example.org/address",
97
- },
98
- ],
99
- maxCardinality: 1,
100
- minCardinality: 0,
101
- iri: "http://example.org/address",
102
- readablePredicate: "address",
103
- // `extra` here enables that if multiple children are present but only one is valid, the shape is still considered valid.
104
- extra: true,
105
- },
106
- ],
107
- },
108
- "http://example.org/PersonShape||http://example.org/address": {
109
- iri: "http://example.org/PersonShape||http://example.org/address",
110
- predicates: [
111
- {
112
- dataTypes: [{ valType: "string" }],
113
- maxCardinality: 1,
114
- minCardinality: 1,
115
- iri: "http://example.org/city",
116
- readablePredicate: "city",
117
- },
118
- ],
119
- },
120
- };
121
- ```
122
-
123
- #### Readable Predicate Names
124
-
125
- The `readablePredicate` field is automatically generated from the predicate IRI and becomes the property name in the TypeScript interface.
126
-
127
- **Generation Rules:**
128
-
129
- 1. **Special case**: `rdf:type` (`http://www.w3.org/1999/02/22-rdf-syntax-ns#type`) always becomes `@type`
130
-
131
- 2. **No conflicts**: If the last segment of the IRI is unique within the shape, it's used as-is:
132
- - `http://example.org/name` → `name`
133
- - `http://schema.org/email` → `email`
134
-
135
- 3. **Conflict resolution**: When multiple predicates in the same shape share the same last segment (local name), **all** predicates in that collision group are renamed using prefixes:
136
- - The algorithm walks backward through IRI segments (right to left)
137
- - For each predicate, it tries `{prefix}_{localName}` combinations until finding an unused name
138
- - Example: Both `http://foaf.org/name` and `http://schema.org/name` would become `foaf_name` and `schema_name`
139
-
140
- 4. **Fallback**: If prefix combinations are exhausted, a composite name is generated from all IRI segments (excluding protocol) with incrementing numbers for uniqueness:
141
- - Pattern: `{composite}_{localName}` or `{composite}_{localName}_1`, `{composite}_{localName}_2`, etc.
142
-
143
- **Character sanitization**: Special characters (except dots and dashes) are replaced with underscores to ensure valid JavaScript identifiers.
144
-
145
- **Note**: You can **manually edit** the `readablePredicate` values in the generated schema files if you prefer different property names. The schema acts as the single source of truth for property naming.
146
-
147
- ### Typings File
148
-
149
- ```ts
150
- export type IRI = string;
151
-
152
- export interface Person {
153
- readonly "@id": IRI;
154
- readonly "@graph": IRI;
155
- /**
156
- * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
157
- */
158
- "@type": "http://example.org/Person";
159
- /**
160
- * Original IRI: http://example.org/name
161
- */
162
- name: string;
163
- /**
164
- * Original IRI: http://example.org/email
165
- */
166
- email?: Set<string>;
167
- /**
168
- * Original IRI: http://example.org/address
169
- */
170
- address?: {
171
- readonly "@id": IRI;
172
- readonly "@graph": IRI;
173
- /**
174
- * Original IRI: http://example.org/city
175
- */
176
- city: string;
177
- };
178
- }
179
- ```
180
-
181
- #### Standard Properties
85
+ #### Default Properties
182
86
 
183
87
  - **`@type`**: The RDF type IRI (from `rdf:type`) is always converted to the property name `@type` by default
184
- - **`@id` and `@graph`**: These properties are automatically added to all typed objects as readonly properties
88
+ - **`@id` (subject IRI) and `@graph` (graph NURI)**: These properties are automatically added to all typed objects as readonly properties
185
89
 
186
90
  ### Cardinality Handling
187
91
 
package/dist/schema-converter/transformers/ShexJTypingTransformer.js CHANGED
@@ -293,7 +293,7 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer({
293
293
  const propsToAdd = [];
294
294
  if (!hasGraph) {
295
295
  const graphProp = dom.create.property("@graph", dom.create.namedTypeReference("IRI"), dom.DeclarationFlags.ReadOnly);
296
- graphProp.jsDocComment = "The graph IRI.";
296
+ graphProp.jsDocComment = "The graph NURI.";
297
297
  propsToAdd.push(graphProp);
298
298
  }
299
299
  if (!hasId) {
package/dist/types.d.ts CHANGED
@@ -1,20 +1,29 @@
1
1
  /**
2
- * TODO: Short documentation on schema generation
2
+ * The ORM shape type generated from a [SHEX](https://shex.io/) schema with
3
+ * `rdf-orm build --input ./path/to/shex-files --output ./path/to/shape-types`
3
4
  */
4
5
  export interface ShapeType<T extends BaseType> {
6
+ /** The schema object of the shape. */
5
7
  schema: Schema;
8
+ /** The ID (IRI) of the shape. */
6
9
  shape: string;
7
10
  }
11
+ /** The base type that all generated objects inherit from. */
8
12
  export interface BaseType extends Record<string, any> {
13
+ /** The IRI of the subject. */
9
14
  "@id": string;
10
15
  }
11
16
  export type Schema = {
12
17
  [id: string]: Shape;
13
18
  };
19
+ /** Shape of an object. */
14
20
  export interface Shape {
21
+ /** The ID (IRI) of the shape. */
15
22
  iri: string;
23
+ /** The predicates (properties) of the shape. */
16
24
  predicates: Predicate[];
17
25
  }
26
+ /** An allowed data type or literal. */
18
27
  export type DataType = {
19
28
  /** The required literal value(s). Additional values are allowed, if `extra` is true. */
20
29
  literals?: number[] | string[] | boolean;
@@ -23,6 +32,7 @@ export type DataType = {
23
32
  /** The type of object value for a triple constraint. */
24
33
  valType: "number" | "string" | "boolean" | "iri" | "shape";
25
34
  };
35
+ /** The schema of a property. */
26
36
  export interface Predicate {
27
37
  /** Allowed type of object. If more than one is present, either of them is allowed. */
28
38
  dataTypes: DataType[];
@@ -32,7 +42,7 @@ export interface Predicate {
32
42
  readablePredicate: string;
33
43
  /** Maximum allowed number of values. `-1` means infinite. */
34
44
  maxCardinality: number;
35
- /** Minimum required number of values */
45
+ /** Minimum required number of values. */
36
46
  minCardinality: number;
37
47
  /** If other (additional) values are permitted. Useful for literals. */
38
48
  extra?: boolean;
package/dist/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,QAAQ;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,MAAM,GAAG;IACjB,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,KAAK;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,SAAS,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG;IACnB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACzC,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,wDAAwD;IACxD,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;CAC9D,CAAC;AAEF,MAAM,WAAW,SAAS;IACtB,sFAAsF;IACtF,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,QAAQ;IACzC,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACjD,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CAIjB;AAED,MAAM,MAAM,MAAM,GAAG;IACjB,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB,CAAC;AAEF,0BAA0B;AAC1B,MAAM,WAAW,KAAK;IAClB,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,UAAU,EAAE,SAAS,EAAE,CAAC;CAC3B;AAED,uCAAuC;AACvC,MAAM,MAAM,QAAQ,GAAG;IACnB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACzC,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,wDAAwD;IACxD,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;CAC9D,CAAC;AAEF,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACtB,sFAAsF;IACtF,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ng-org/shex-orm",
3
- "version": "0.1.2-alpha.4",
3
+ "version": "0.1.2-alpha.5",
4
4
  "description": "",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",