@cyphra/schema 0.1.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/README.md ADDED
@@ -0,0 +1,17 @@
1
+ # @cyphra/schema
2
+
3
+ Parser and AST types for the Cyphra `.cyphra` schema DSL.
4
+
5
+ ## Usage
6
+
7
+ ```ts
8
+ import { parseSchema } from "@cyphra/schema";
9
+
10
+ const doc = parseSchema(`
11
+ node User {
12
+ id String @id @default(cuid())
13
+ }
14
+ `);
15
+ ```
16
+
17
+ See the main Cyphra documentation site for the full grammar.
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Discriminated AST for parsed `.cyphra` schema documents.
3
+ *
4
+ * @packageDocumentation
5
+ */
6
+ /** Root document produced by the parser (before semantic validation). */
7
+ type SchemaDocument = {
8
+ readonly kind: "Document";
9
+ readonly declarations: readonly Declaration[];
10
+ };
11
+ type Declaration = NodeDeclaration | RelationshipDeclaration;
12
+ type NodeDeclaration = {
13
+ readonly kind: "Node";
14
+ readonly name: string;
15
+ readonly fields: readonly NodeField[];
16
+ };
17
+ type RelationshipDeclaration = {
18
+ readonly kind: "Relationship";
19
+ readonly name: string;
20
+ readonly relType: string;
21
+ readonly from: string;
22
+ readonly to: string;
23
+ readonly fields: readonly ScalarNodeField[];
24
+ };
25
+ type NodeField = ScalarNodeField | RelationalNodeField;
26
+ type ScalarTypeName = "String" | "Int" | "Float" | "Boolean" | "DateTime";
27
+ type ScalarTypeRef = {
28
+ readonly name: ScalarTypeName;
29
+ readonly optional: boolean;
30
+ };
31
+ type ScalarNodeField = {
32
+ readonly kind: "Scalar";
33
+ readonly name: string;
34
+ readonly type: ScalarTypeRef;
35
+ readonly decorators: readonly Decorator[];
36
+ };
37
+ type RelationalNodeField = {
38
+ readonly kind: "Relational";
39
+ readonly name: string;
40
+ readonly target: string;
41
+ readonly cardinality: "one" | "many";
42
+ readonly optional: boolean;
43
+ readonly decorators: readonly Decorator[];
44
+ };
45
+ /** Parsed decorator such as `@id` or `@relationship(type: "X", direction: OUT)`. */
46
+ type Decorator = {
47
+ readonly name: string;
48
+ readonly args: readonly DecoratorArg[];
49
+ };
50
+ type DecoratorArg = {
51
+ readonly key: string;
52
+ readonly value: DecoratorValue;
53
+ };
54
+ type DecoratorValue = {
55
+ readonly kind: "string";
56
+ readonly value: string;
57
+ } | {
58
+ readonly kind: "identifier";
59
+ readonly value: string;
60
+ };
61
+
62
+ /**
63
+ * Thrown when a `.cyphra` document fails semantic validation after a successful parse.
64
+ */
65
+ declare class SchemaValidationError extends Error {
66
+ readonly name = "SchemaValidationError";
67
+ /**
68
+ * @param message - Human-readable explanation for library consumers.
69
+ */
70
+ constructor(message: string);
71
+ }
72
+
73
+ /**
74
+ * Serialize a decorator back to `.cyphra` surface syntax.
75
+ *
76
+ * @param d - Parsed decorator.
77
+ */
78
+ declare function formatDecorator(d: Decorator): string;
79
+ /**
80
+ * Pretty-print a schema document as `.cyphra` text (comments are not preserved).
81
+ *
82
+ * @param doc - Parsed document.
83
+ * @returns UTF-8 source suitable for review, diffs, or round-trip testing.
84
+ */
85
+ declare function printSchemaDocument(doc: SchemaDocument): string;
86
+
87
+ /** Maximum `.cyphra` source size accepted by {@link parseSchema} (mitigates parser DoS). */
88
+ declare const MAX_SCHEMA_BYTES: number;
89
+ /**
90
+ * Parse a Cyphra schema string into an AST and run semantic validation.
91
+ *
92
+ * @param source - Full contents of a `.cyphra` file (UTF-8).
93
+ * @returns Validated {@link SchemaDocument}.
94
+ * @throws {SyntaxError} From Peggy when the text does not match the grammar (check `location`).
95
+ * @throws {SchemaValidationError} When semantic rules fail.
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * const doc = parseSchema(`
100
+ * node User {
101
+ * id String @id @default(cuid())
102
+ * }
103
+ * `);
104
+ * ```
105
+ */
106
+ declare function parseSchema(source: string): SchemaDocument;
107
+
108
+ /**
109
+ * Read a UTF-8 `.cyphra` file from disk and {@link parseSchema parse} + validate it.
110
+ *
111
+ * @param path - Absolute or relative file path.
112
+ */
113
+ declare function parseSchemaFile(path: string): Promise<SchemaDocument>;
114
+
115
+ /** Data used to emit `cyphra.gen.ts`. */
116
+ type CodegenModel = {
117
+ readonly nodeLabels: readonly string[];
118
+ readonly relationshipModels: readonly {
119
+ readonly name: string;
120
+ readonly neo4jType: string;
121
+ readonly fromLabel: string;
122
+ readonly toLabel: string;
123
+ }[];
124
+ readonly relNeo4jTypes: readonly string[];
125
+ };
126
+ /**
127
+ * Walk the AST and collect labels, relationship models, and all Neo4j relationship types.
128
+ *
129
+ * @param doc - Validated schema document.
130
+ */
131
+ declare function collectCodegenModel(doc: SchemaDocument): CodegenModel;
132
+ /**
133
+ * Turn a Neo4j relationship type string into a stable `RelType` object key (valid identifier).
134
+ *
135
+ * @param type - Value inside `type: "…"` in the schema.
136
+ */
137
+ declare function relTypeToExportKey(type: string, used: Set<string>): string;
138
+ /**
139
+ * Render a `cyphra.gen.ts` module for use with the query builder and migrations.
140
+ *
141
+ * @param doc - Parsed and validated schema.
142
+ */
143
+ declare function renderCyphraGenSource(doc: SchemaDocument): string;
144
+
145
+ /**
146
+ * Applies semantic rules that the grammar cannot express (e.g. a single `@id` per node).
147
+ *
148
+ * @param doc - Parsed document from {@link parseSchema} (parse phase only).
149
+ * @throws {SchemaValidationError} When a rule is violated.
150
+ */
151
+ declare function validateSchema(doc: SchemaDocument): void;
152
+
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 };