@yrest/cli 0.8.1 → 0.10.0

package/dist/index.d.mts

@@ -4,23 +4,107 @@ import * as http from 'http';
 
 /** A single REST resource item. Field names and value types are user-defined in the YAML file. */
 type Resource = Record<string, unknown>;
+/**
+ * Descriptor for a single field declared in the `_schema` block.
+ *
+ * All properties are optional — omit what you don't need. Fields not mentioned
+ * in `_schema` are inferred from the collection data and treated as optional.
+ *
+ * Shorthand: `fieldName: required` normalises to `{ required: true }`.
+ */
+type FieldDef = {
+    /** If `true`, the field is listed in the OpenAPI `required` array and (Phase B) validated on POST/PUT. */
+    required?: boolean;
+    /** Explicit type override. If absent, inferred from the data. */
+    type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
+    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`). */
+    format?: string;
+    /** Restricts the field to a fixed set of values. */
+    enum?: unknown[];
+    /** Human-readable description included in the OpenAPI spec. */
+    description?: string;
+    /** Default value included in the OpenAPI spec. */
+    default?: unknown;
+};
+/**
+ * Field-level schema declarations for one or more collections, parsed from `_schema` in the YAML.
+ *
+ * - Outer key: collection name.
+ * - Inner key: field name within that collection.
+ * - Value: {@link FieldDef} descriptor (or the string shorthand `"required"` / `"optional"`).
+ *
+ * @example
+ * ```yaml
+ * _schema:
+ *   users:
+ *     name: required          # shorthand
+ *     email:
+ *       required: true
+ *       format: email
+ *     age:
+ *       type: integer
+ * ```
+ */
+type SchemaBlock = Record<string, Record<string, FieldDef>>;
 /**
  * The full in-memory database.
  * Keys are collection names (e.g. `"users"`); values are arrays of {@link Resource} items.
  */
 type Data = Record<string, Resource[]>;
 /**
- * Relational mappings declared under `_rel` in the YAML file.
+ * Canonical descriptor for a single relation declared under `_rel`.
+ *
+ * The YAML accepts two forms that both normalise to this type:
+ * - **Shorthand string** — `userId: users` → `{ type: "many2one", target: "users" }`
+ * - **Object** — explicit `type` plus the fields required by that type.
+ *
+ * ### Types
+ * - `many2one` — (default) many children share one parent via a FK field.
+ * - `one2one`  — one child belongs to one parent; `?_embed` returns a single object, not an array.
+ * - `many2many` — join through a pivot collection; the relation key is the embed alias.
+ *
+ * @example
+ * // _rel:
+ * //   posts:
+ * //     userId: users                        ← shorthand many2one
+ * //     tags:
+ * //       type: many2many
+ * //       through: post_tags
+ * //       foreignKey: postId
+ * //       otherKey: tagId
+ * //   users:
+ * //     profileId:
+ * //       type: one2one
+ * //       target: profiles
+ */
+type RelationDef = {
+    type: "many2one";
+    target: string;
+    nested?: boolean;
+} | {
+    type: "one2one";
+    target: string;
+    nested?: boolean;
+} | {
+    type: "many2many";
+    target: string;
+    through: string;
+    foreignKey: string;
+    otherKey: string;
+    nested?: boolean;
+};
+/**
+ * Relational mappings declared under `_rel` in the YAML file, normalised to {@link RelationDef}.
  *
- * - Outer key: child collection name.
- * - Inner key: foreign key field on the child.
- * - Inner value: parent collection name.
+ * - Outer key: source collection name (child for many2one/one2one; either side for many2many).
+ * - Inner key: FK field name (many2one/one2one) or embed alias (many2many).
+ * - Inner value: canonical {@link RelationDef}.
  *
  * @example
  * // Given: _rel: { posts: { userId: users } }
  * // GET /users/1/posts → returns posts where userId === "1"
  */
-type Relations = Record<string, Record<string, string>>;
+type Relations = Record<string, Record<string, RelationDef>>;
 /**
  * A static response block shared by {@link CustomRoute} and {@link Scenario}.
  */
@@ -138,6 +222,8 @@ interface YrestStorage {
     getData(): Data;
     /** Returns the relational mappings declared under `_rel`. */
     getRelations(): Relations;
+    /** Returns the field-level schema declarations from `_schema`, or `{}` if absent. */
+    getSchema(): SchemaBlock;
     /**
      * Returns the items in a named collection, or `undefined` if it does not exist.
      *

package/dist/index.d.ts

@@ -4,23 +4,107 @@ import * as http from 'http';
 
 /** A single REST resource item. Field names and value types are user-defined in the YAML file. */
 type Resource = Record<string, unknown>;
+/**
+ * Descriptor for a single field declared in the `_schema` block.
+ *
+ * All properties are optional — omit what you don't need. Fields not mentioned
+ * in `_schema` are inferred from the collection data and treated as optional.
+ *
+ * Shorthand: `fieldName: required` normalises to `{ required: true }`.
+ */
+type FieldDef = {
+    /** If `true`, the field is listed in the OpenAPI `required` array and (Phase B) validated on POST/PUT. */
+    required?: boolean;
+    /** Explicit type override. If absent, inferred from the data. */
+    type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
+    /** OpenAPI `format` hint (e.g. `email`, `date`, `uuid`, `uri`, `date-time`). */
+    format?: string;
+    /** Restricts the field to a fixed set of values. */
+    enum?: unknown[];
+    /** Human-readable description included in the OpenAPI spec. */
+    description?: string;
+    /** Default value included in the OpenAPI spec. */
+    default?: unknown;
+};
+/**
+ * Field-level schema declarations for one or more collections, parsed from `_schema` in the YAML.
+ *
+ * - Outer key: collection name.
+ * - Inner key: field name within that collection.
+ * - Value: {@link FieldDef} descriptor (or the string shorthand `"required"` / `"optional"`).
+ *
+ * @example
+ * ```yaml
+ * _schema:
+ *   users:
+ *     name: required          # shorthand
+ *     email:
+ *       required: true
+ *       format: email
+ *     age:
+ *       type: integer
+ * ```
+ */
+type SchemaBlock = Record<string, Record<string, FieldDef>>;
 /**
  * The full in-memory database.
  * Keys are collection names (e.g. `"users"`); values are arrays of {@link Resource} items.
  */
 type Data = Record<string, Resource[]>;
 /**
- * Relational mappings declared under `_rel` in the YAML file.
+ * Canonical descriptor for a single relation declared under `_rel`.
+ *
+ * The YAML accepts two forms that both normalise to this type:
+ * - **Shorthand string** — `userId: users` → `{ type: "many2one", target: "users" }`
+ * - **Object** — explicit `type` plus the fields required by that type.
+ *
+ * ### Types
+ * - `many2one` — (default) many children share one parent via a FK field.
+ * - `one2one`  — one child belongs to one parent; `?_embed` returns a single object, not an array.
+ * - `many2many` — join through a pivot collection; the relation key is the embed alias.
+ *
+ * @example
+ * // _rel:
+ * //   posts:
+ * //     userId: users                        ← shorthand many2one
+ * //     tags:
+ * //       type: many2many
+ * //       through: post_tags
+ * //       foreignKey: postId
+ * //       otherKey: tagId
+ * //   users:
+ * //     profileId:
+ * //       type: one2one
+ * //       target: profiles
+ */
+type RelationDef = {
+    type: "many2one";
+    target: string;
+    nested?: boolean;
+} | {
+    type: "one2one";
+    target: string;
+    nested?: boolean;
+} | {
+    type: "many2many";
+    target: string;
+    through: string;
+    foreignKey: string;
+    otherKey: string;
+    nested?: boolean;
+};
+/**
+ * Relational mappings declared under `_rel` in the YAML file, normalised to {@link RelationDef}.
  *
- * - Outer key: child collection name.
- * - Inner key: foreign key field on the child.
- * - Inner value: parent collection name.
+ * - Outer key: source collection name (child for many2one/one2one; either side for many2many).
+ * - Inner key: FK field name (many2one/one2one) or embed alias (many2many).
+ * - Inner value: canonical {@link RelationDef}.
  *
  * @example
  * // Given: _rel: { posts: { userId: users } }
  * // GET /users/1/posts → returns posts where userId === "1"
  */
-type Relations = Record<string, Record<string, string>>;
+type Relations = Record<string, Record<string, RelationDef>>;
 /**
  * A static response block shared by {@link CustomRoute} and {@link Scenario}.
  */
@@ -138,6 +222,8 @@ interface YrestStorage {
     getData(): Data;
     /** Returns the relational mappings declared under `_rel`. */
     getRelations(): Relations;
+    /** Returns the field-level schema declarations from `_schema`, or `{}` if absent. */
+    getSchema(): SchemaBlock;
     /**
      * Returns the items in a named collection, or `undefined` if it does not exist.
      *