@cyphra/schema 0.1.0 → 0.2.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Cyphra contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/index.d.ts CHANGED
@@ -23,10 +23,12 @@ type RelationshipDeclaration = {
23
23
  readonly fields: readonly ScalarNodeField[];
24
24
  };
25
25
  type NodeField = ScalarNodeField | RelationalNodeField;
26
- type ScalarTypeName = "String" | "Int" | "Float" | "Boolean" | "DateTime";
26
+ type ScalarTypeName = "String" | "Int" | "Float" | "Boolean" | "DateTime" | "Date";
27
27
  type ScalarTypeRef = {
28
28
  readonly name: ScalarTypeName;
29
29
  readonly optional: boolean;
30
+ /** `String[]`-style scalar list (lists are never optional; an absent list reads as `[]`). */
31
+ readonly list?: boolean;
30
32
  };
31
33
  type ScalarNodeField = {
32
34
  readonly kind: "Scalar";
@@ -54,6 +56,12 @@ type DecoratorArg = {
54
56
  type DecoratorValue = {
55
57
  readonly kind: "string";
56
58
  readonly value: string;
59
+ } | {
60
+ readonly kind: "number";
61
+ readonly value: number;
62
+ } | {
63
+ readonly kind: "boolean";
64
+ readonly value: boolean;
57
65
  } | {
58
66
  readonly kind: "identifier";
59
67
  readonly value: string;
@@ -112,6 +120,100 @@ declare function parseSchema(source: string): SchemaDocument;
112
120
  */
113
121
  declare function parseSchemaFile(path: string): Promise<SchemaDocument>;
114
122
 
123
+ /**
124
+ * Resolved schema model: the normalized, JSON-serializable form of a `.cyphra` schema.
125
+ *
126
+ * The parser produces a surface-level AST ({@link SchemaDocument}); {@link resolveSchema} turns it into
127
+ * a {@link SchemaModel} with relations linked, defaults typed, and cross-references checked. Everything
128
+ * downstream — the generated typed client, the ORM runtime, and schema-diff migrations — reads this
129
+ * model, never the AST.
130
+ *
131
+ * @packageDocumentation
132
+ */
133
+
134
+ /** Bump when the shape of {@link SchemaModel} changes incompatibly. */
135
+ declare const SCHEMA_MODEL_VERSION: 1;
136
+ /** Built-in generator functions accepted by `@default(fn())`. */
137
+ type DefaultFunction = "cuid" | "uuid" | "now";
138
+ type DefaultValueSpec = {
139
+ readonly kind: "fn";
140
+ readonly fn: DefaultFunction;
141
+ } | {
142
+ readonly kind: "literal";
143
+ readonly value: string | number | boolean;
144
+ };
145
+ type ResolvedScalarField = {
146
+ readonly kind: "scalar";
147
+ readonly name: string;
148
+ readonly type: ScalarTypeName;
149
+ /** `true` when the property may be absent / `null`. Lists are never optional. */
150
+ readonly optional: boolean;
151
+ readonly list: boolean;
152
+ readonly id: boolean;
153
+ readonly unique: boolean;
154
+ readonly index: boolean;
155
+ readonly default?: DefaultValueSpec;
156
+ };
157
+ type RelationDirection = "OUT" | "IN";
158
+ type ResolvedRelationField = {
159
+ readonly kind: "relation";
160
+ readonly name: string;
161
+ /** Target node model name. */
162
+ readonly target: string;
163
+ /** Neo4j relationship type, e.g. `AUTHORED`. */
164
+ readonly relType: string;
165
+ /** `OUT`: `(this)-[:T]->(target)`; `IN`: `(this)<-[:T]-(target)`. */
166
+ readonly direction: RelationDirection;
167
+ readonly many: boolean;
168
+ readonly optional: boolean;
169
+ /** Name of the `relationship { … }` model that types this edge's properties, if any. */
170
+ readonly edge?: string;
171
+ };
172
+ type ResolvedField = ResolvedScalarField | ResolvedRelationField;
173
+ type ResolvedNodeModel = {
174
+ readonly name: string;
175
+ /** Neo4j label (currently always the model name). */
176
+ readonly label: string;
177
+ /** Name of the `@id` field, if any. */
178
+ readonly idField?: string;
179
+ /** `@id` and `@unique` scalar fields — valid keys for `findUnique` / `connect`. */
180
+ readonly uniqueFields: readonly string[];
181
+ /** Fields in declaration order. */
182
+ readonly fields: readonly ResolvedField[];
183
+ };
184
+ type ResolvedRelationshipModel = {
185
+ readonly name: string;
186
+ readonly relType: string;
187
+ readonly from: string;
188
+ readonly to: string;
189
+ readonly properties: readonly ResolvedScalarField[];
190
+ };
191
+ type SchemaModel = {
192
+ readonly version: typeof SCHEMA_MODEL_VERSION;
193
+ readonly nodes: readonly ResolvedNodeModel[];
194
+ readonly relationships: readonly ResolvedRelationshipModel[];
195
+ };
196
+ /**
197
+ * Resolve a parsed document into a {@link SchemaModel}: link relations to their targets and
198
+ * relationship models, type defaults, and check every cross-reference.
199
+ *
200
+ * @param doc - Output of {@link parseSchema}.
201
+ * @throws {SchemaValidationError} On unknown targets, bad defaults, ambiguous edges, etc.
202
+ */
203
+ declare function resolveSchema(doc: SchemaDocument): SchemaModel;
204
+ /** Look up a node model by name. */
205
+ declare function getNodeModel(model: SchemaModel, name: string): ResolvedNodeModel;
206
+
207
+ /** Options for {@link renderCyphraGenSource}. */
208
+ type RenderCyphraGenOptions = {
209
+ /**
210
+ * Module the generated client imports its runtime from (default `"cyphra"`).
211
+ * Use `"@cyphra/runtime"` if you depend on the runtime package directly.
212
+ */
213
+ readonly runtimeImport?: string;
214
+ };
215
+ /** Render the typed ORM section (model types, type map, schema model, `createClient`). */
216
+ declare function renderClientSection(model: SchemaModel): string[];
115
217
  /** Data used to emit `cyphra.gen.ts`. */
116
218
  type CodegenModel = {
117
219
  readonly nodeLabels: readonly string[];
@@ -140,7 +242,7 @@ declare function relTypeToExportKey(type: string, used: Set<string>): string;
140
242
  *
141
243
  * @param doc - Parsed and validated schema.
142
244
  */
143
- declare function renderCyphraGenSource(doc: SchemaDocument): string;
245
+ declare function renderCyphraGenSource(doc: SchemaDocument, options?: RenderCyphraGenOptions): string;
144
246
 
145
247
  /**
146
248
  * Applies semantic rules that the grammar cannot express (e.g. a single `@id` per node).
@@ -150,4 +252,4 @@ declare function renderCyphraGenSource(doc: SchemaDocument): string;
150
252
  */
151
253
  declare function validateSchema(doc: SchemaDocument): void;
152
254
 
153
- export { type CodegenModel, type Declaration, type Decorator, type DecoratorArg, type DecoratorValue, MAX_SCHEMA_BYTES, type NodeDeclaration, type NodeField, type RelationalNodeField, type RelationshipDeclaration, type ScalarNodeField, type ScalarTypeName, type ScalarTypeRef, type SchemaDocument, SchemaValidationError, collectCodegenModel, formatDecorator, parseSchema, parseSchemaFile, printSchemaDocument, relTypeToExportKey, renderCyphraGenSource, validateSchema };
255
+ export { type CodegenModel, type Declaration, type Decorator, type DecoratorArg, type DecoratorValue, type DefaultFunction, type DefaultValueSpec, MAX_SCHEMA_BYTES, type NodeDeclaration, type NodeField, type RelationDirection, type RelationalNodeField, type RelationshipDeclaration, type RenderCyphraGenOptions, type ResolvedField, type ResolvedNodeModel, type ResolvedRelationField, type ResolvedRelationshipModel, type ResolvedScalarField, SCHEMA_MODEL_VERSION, type ScalarNodeField, type ScalarTypeName, type ScalarTypeRef, type SchemaDocument, type SchemaModel, SchemaValidationError, collectCodegenModel, formatDecorator, getNodeModel, parseSchema, parseSchemaFile, printSchemaDocument, relTypeToExportKey, renderClientSection, renderCyphraGenSource, resolveSchema, validateSchema };