@yrest/cli 0.13.0 → 0.14.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ServerResponse } from 'node:http';
 import * as fastify from 'fastify';
 import * as http from 'http';
 
@@ -105,10 +106,10 @@ type FieldDef = {
  *   users:
  *     name: required          # shorthand
  *     email:
- *       required: true
- *       format: email
+ *       _required: true
+ *       _format: email
  *     age:
- *       type: integer
+ *       _type: integer
  * ```
  */
 type SchemaBlock = Record<string, Record<string, FieldDef>>;
@@ -317,8 +318,13 @@ type SseRoute = {
     loop: boolean;
     /** Stop after this many full cycles. Omit for infinite. */
     repeat?: number;
-    /** Ordered list of events to emit. */
+    /** Ordered list of events to emit. Empty when {@link SseRoute.handler} drives the stream. */
     events: SseEvent[];
+    /**
+     * Name of an SSE handler exported from the handlers file (`_sse: { _handler: name }`).
+     * When set, the handler takes full control of the stream and `events` is not used.
+     */
+    handler?: string;
 };
 /**
  * In-memory store backed by a YAML file.
@@ -506,6 +512,39 @@ declare const yrestOptionsSchema: z.ZodObject<{
  */
 type YrestOptions = z.infer<typeof yrestOptionsSchema>;
 
+/**
+ * Typed CRUD access to one collection of a running yrest instance.
+ *
+ * Writes go through the same service layer as the REST routes, so they are visible to
+ * HTTP clients immediately and persisted to `db.yml` exactly like a `POST` / `PATCH` /
+ * `DELETE` (a no-op for in-memory data).
+ *
+ * Returned items are copies: mutating them does not change the stored data — use
+ * {@link CollectionHandle.update} instead.
+ *
+ * @typeParam T - Item type, typically generated by `yrest types`.
+ */
+interface CollectionHandle<T extends object = Resource> {
+    /** Every item in the collection, in stored order. */
+    findAll(): T[];
+    /** The item with the given id, or `undefined`. Ids compare as strings (`1` matches `"1"`). */
+    findById(id: string | number): T | undefined;
+    /** Every item for which `predicate` returns `true`. */
+    findWhere(predicate: (item: T) => boolean): T[];
+    /** Number of items in the collection. */
+    count(): number;
+    /** Adds an item. The `id` is generated with the server's id strategy when omitted. */
+    create(data: Omit<T, "id"> & {
+        id?: unknown;
+    }): T;
+    /** Merges `patch` into the item. The `id` cannot be changed. Returns `undefined` if not found. */
+    update(id: string | number, patch: Partial<Omit<T, "id">>): T | undefined;
+    /** Removes the item and returns it, or `undefined` if not found. */
+    delete(id: string | number): T | undefined;
+}
+/** Function that returns a {@link CollectionHandle} for a collection name. */
+type CollectionAccessor = <T extends object = Resource>(name: string) => CollectionHandle<T>;
+
 /** Incoming request data passed to every handler function. */
 type HandlerRequest = {
     params: Record<string, string>;
@@ -522,10 +561,60 @@ type HandlerResponse = {
     /** Additional response headers to set on the reply. */
     headers?: Record<string, string>;
 };
+/**
+ * Server context passed to every handler as its last argument.
+ *
+ * Gives handlers typed access to the live collections, so a mock can read and change the
+ * same data the REST routes serve (e.g. a login handler that looks the user up).
+ */
+type HandlerContext = {
+    /** Returns a typed CRUD handle for a collection. Throws if the collection does not exist. */
+    collection: CollectionAccessor;
+};
 /** A function that handles a custom route request and returns a response descriptor. */
-type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>;
-/** Map of exported function name → handler function. */
-type HandlerMap = Map<string, Handler>;
+type Handler = (req: HandlerRequest, ctx: HandlerContext) => HandlerResponse | Promise<HandlerResponse>;
+/**
+ * A function that takes full control of an SSE stream (`_sse: { _handler: name }`).
+ *
+ * yrest sets the SSE headers, flushes them and sends a keep-alive comment every 15 s.
+ * The handler writes frames to `raw` and decides when to `raw.end()`. Listen to
+ * `raw.on("close", ...)` to stop work when the client disconnects.
+ */
+type SseHandler = (req: HandlerRequest, raw: ServerResponse, ctx: HandlerContext) => void | Promise<void>;
+/** Map of exported function name → handler function (HTTP or SSE). */
+type HandlerMap = Map<string, Handler | SseHandler>;
+/**
+ * Identity wrapper that types a custom route handler. It has no runtime effect.
+ *
+ * @example
+ * ```ts
+ * import { defineHandler } from "@yrest/cli";
+ * import type { User } from "./db.types";
+ *
+ * export const login = defineHandler((req, { collection }) => {
+ *   const { email } = (req.body ?? {}) as { email?: string };
+ *   const user = collection<User>("users").findWhere((u) => u.email === email)[0];
+ *   return user ? { body: { token: `tok-${user.id}` } } : { status: 401, body: { error: "Unknown user" } };
+ * });
+ * ```
+ */
+declare function defineHandler(fn: Handler): Handler;
+/**
+ * Identity wrapper that types an SSE stream handler. It has no runtime effect.
+ *
+ * @example
+ * ```ts
+ * import { defineSseHandler } from "@yrest/cli";
+ *
+ * export const clock = defineSseHandler((req, raw) => {
+ *   const timer = setInterval(() => {
+ *     raw.write(`event: tick\ndata: ${JSON.stringify({ now: Date.now() })}\n\n`);
+ *   }, 1000);
+ *   raw.on("close", () => clearInterval(timer));
+ * });
+ * ```
+ */
+declare function defineSseHandler(fn: SseHandler): SseHandler;
 
 /**
  * Creates and configures a Fastify instance wired to the given YAML storage.
@@ -555,6 +644,21 @@ interface YrestServer {
     readonly port: number;
     /** The base URL of the server (e.g. `http://localhost:3070`). Only valid after `start()`. */
     readonly url: string;
+    /**
+     * Returns a typed CRUD handle for a collection of the running data.
+     * Changes are visible to HTTP clients immediately and persisted like REST writes.
+     *
+     * @example
+     * ```ts
+     * import type { User } from "./db.types"; // from `yrest types`
+     * const users = server.collection<User>("users");
+     * users.create({ name: "Ana" });
+     * expect(users.findAll()).toHaveLength(1);
+     * ```
+     *
+     * @throws {Error} If the collection does not exist, or (for `createYrestServer`) before `start()`.
+     */
+    collection<T extends object = Resource>(name: string): CollectionHandle<T>;
 }
 /**
  * Creates a {@link YrestServer} from an already-initialised storage and parsed options.
@@ -642,4 +746,32 @@ declare function createYrestServer(options: YrestServerOptions): YrestServer;
 
 declare function createYrestStorage(filePath: string): YrestStorage;
 
-export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type YrestOptions, type YrestServer, type YrestServerBaseOptions, type YrestServerOptions, type YrestStorage, createServer, createYrestServer, createYrestServerFromStorage, createYrestStorage, yrest, yrestOptionsSchema };
+/** Input for {@link generateTypes}: the parsed pieces of a `db.yml` file. */
+type GenerateTypesInput = {
+    /** Collections and their items. */
+    data: Data;
+    /** Field-level declarations from `_schema` (optional). */
+    schema?: SchemaBlock;
+    /** Relations from `_rel` — used to annotate FK fields (optional). */
+    relations?: Relations;
+};
+/** Options for {@link generateTypes}. */
+type GenerateTypesOptions = {
+    /** Source file name shown in the header comment (e.g. `"db.yml"`). */
+    source?: string;
+};
+/**
+ * Generates TypeScript declarations from a yrest dataset.
+ *
+ * - One `interface` per collection, named in singular PascalCase (`post_tags` → `PostTag`).
+ * - Types are inferred from **all** items; a field missing on any item is optional.
+ * - `_schema` declarations override inference (`_type`, `_required`, `_enum`, `_nullable`, `_items`)
+ *   and add JSDoc (`_description`, `_format`, `_deprecated`).
+ * - `_rel` many2one/one2one FK fields get a `FK → target.id` JSDoc note.
+ * - Ends with a `CollectionName` union and a `Collections` map (`{ users: User[] }`).
+ *
+ * Output is deterministic: collections and fields keep their order of appearance.
+ */
+declare function generateTypes(input: GenerateTypesInput, options?: GenerateTypesOptions): string;
+
+export { type CollectionAccessor, type CollectionHandle, type CustomRoute, type Data, type GenerateTypesInput, type GenerateTypesOptions, type Handler, type HandlerContext, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type SseHandler, type YrestOptions, type YrestServer, type YrestServerBaseOptions, type YrestServerOptions, type YrestStorage, createServer, createYrestServer, createYrestServerFromStorage, createYrestStorage, defineHandler, defineSseHandler, generateTypes, yrest, yrestOptionsSchema };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ServerResponse } from 'node:http';
 import * as fastify from 'fastify';
 import * as http from 'http';
 
@@ -105,10 +106,10 @@ type FieldDef = {
  *   users:
  *     name: required          # shorthand
  *     email:
- *       required: true
- *       format: email
+ *       _required: true
+ *       _format: email
  *     age:
- *       type: integer
+ *       _type: integer
  * ```
  */
 type SchemaBlock = Record<string, Record<string, FieldDef>>;
@@ -317,8 +318,13 @@ type SseRoute = {
     loop: boolean;
     /** Stop after this many full cycles. Omit for infinite. */
     repeat?: number;
-    /** Ordered list of events to emit. */
+    /** Ordered list of events to emit. Empty when {@link SseRoute.handler} drives the stream. */
     events: SseEvent[];
+    /**
+     * Name of an SSE handler exported from the handlers file (`_sse: { _handler: name }`).
+     * When set, the handler takes full control of the stream and `events` is not used.
+     */
+    handler?: string;
 };
 /**
  * In-memory store backed by a YAML file.
@@ -506,6 +512,39 @@ declare const yrestOptionsSchema: z.ZodObject<{
  */
 type YrestOptions = z.infer<typeof yrestOptionsSchema>;
 
+/**
+ * Typed CRUD access to one collection of a running yrest instance.
+ *
+ * Writes go through the same service layer as the REST routes, so they are visible to
+ * HTTP clients immediately and persisted to `db.yml` exactly like a `POST` / `PATCH` /
+ * `DELETE` (a no-op for in-memory data).
+ *
+ * Returned items are copies: mutating them does not change the stored data — use
+ * {@link CollectionHandle.update} instead.
+ *
+ * @typeParam T - Item type, typically generated by `yrest types`.
+ */
+interface CollectionHandle<T extends object = Resource> {
+    /** Every item in the collection, in stored order. */
+    findAll(): T[];
+    /** The item with the given id, or `undefined`. Ids compare as strings (`1` matches `"1"`). */
+    findById(id: string | number): T | undefined;
+    /** Every item for which `predicate` returns `true`. */
+    findWhere(predicate: (item: T) => boolean): T[];
+    /** Number of items in the collection. */
+    count(): number;
+    /** Adds an item. The `id` is generated with the server's id strategy when omitted. */
+    create(data: Omit<T, "id"> & {
+        id?: unknown;
+    }): T;
+    /** Merges `patch` into the item. The `id` cannot be changed. Returns `undefined` if not found. */
+    update(id: string | number, patch: Partial<Omit<T, "id">>): T | undefined;
+    /** Removes the item and returns it, or `undefined` if not found. */
+    delete(id: string | number): T | undefined;
+}
+/** Function that returns a {@link CollectionHandle} for a collection name. */
+type CollectionAccessor = <T extends object = Resource>(name: string) => CollectionHandle<T>;
+
 /** Incoming request data passed to every handler function. */
 type HandlerRequest = {
     params: Record<string, string>;
@@ -522,10 +561,60 @@ type HandlerResponse = {
     /** Additional response headers to set on the reply. */
     headers?: Record<string, string>;
 };
+/**
+ * Server context passed to every handler as its last argument.
+ *
+ * Gives handlers typed access to the live collections, so a mock can read and change the
+ * same data the REST routes serve (e.g. a login handler that looks the user up).
+ */
+type HandlerContext = {
+    /** Returns a typed CRUD handle for a collection. Throws if the collection does not exist. */
+    collection: CollectionAccessor;
+};
 /** A function that handles a custom route request and returns a response descriptor. */
-type Handler = (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>;
-/** Map of exported function name → handler function. */
-type HandlerMap = Map<string, Handler>;
+type Handler = (req: HandlerRequest, ctx: HandlerContext) => HandlerResponse | Promise<HandlerResponse>;
+/**
+ * A function that takes full control of an SSE stream (`_sse: { _handler: name }`).
+ *
+ * yrest sets the SSE headers, flushes them and sends a keep-alive comment every 15 s.
+ * The handler writes frames to `raw` and decides when to `raw.end()`. Listen to
+ * `raw.on("close", ...)` to stop work when the client disconnects.
+ */
+type SseHandler = (req: HandlerRequest, raw: ServerResponse, ctx: HandlerContext) => void | Promise<void>;
+/** Map of exported function name → handler function (HTTP or SSE). */
+type HandlerMap = Map<string, Handler | SseHandler>;
+/**
+ * Identity wrapper that types a custom route handler. It has no runtime effect.
+ *
+ * @example
+ * ```ts
+ * import { defineHandler } from "@yrest/cli";
+ * import type { User } from "./db.types";
+ *
+ * export const login = defineHandler((req, { collection }) => {
+ *   const { email } = (req.body ?? {}) as { email?: string };
+ *   const user = collection<User>("users").findWhere((u) => u.email === email)[0];
+ *   return user ? { body: { token: `tok-${user.id}` } } : { status: 401, body: { error: "Unknown user" } };
+ * });
+ * ```
+ */
+declare function defineHandler(fn: Handler): Handler;
+/**
+ * Identity wrapper that types an SSE stream handler. It has no runtime effect.
+ *
+ * @example
+ * ```ts
+ * import { defineSseHandler } from "@yrest/cli";
+ *
+ * export const clock = defineSseHandler((req, raw) => {
+ *   const timer = setInterval(() => {
+ *     raw.write(`event: tick\ndata: ${JSON.stringify({ now: Date.now() })}\n\n`);
+ *   }, 1000);
+ *   raw.on("close", () => clearInterval(timer));
+ * });
+ * ```
+ */
+declare function defineSseHandler(fn: SseHandler): SseHandler;
 
 /**
  * Creates and configures a Fastify instance wired to the given YAML storage.
@@ -555,6 +644,21 @@ interface YrestServer {
     readonly port: number;
     /** The base URL of the server (e.g. `http://localhost:3070`). Only valid after `start()`. */
     readonly url: string;
+    /**
+     * Returns a typed CRUD handle for a collection of the running data.
+     * Changes are visible to HTTP clients immediately and persisted like REST writes.
+     *
+     * @example
+     * ```ts
+     * import type { User } from "./db.types"; // from `yrest types`
+     * const users = server.collection<User>("users");
+     * users.create({ name: "Ana" });
+     * expect(users.findAll()).toHaveLength(1);
+     * ```
+     *
+     * @throws {Error} If the collection does not exist, or (for `createYrestServer`) before `start()`.
+     */
+    collection<T extends object = Resource>(name: string): CollectionHandle<T>;
 }
 /**
  * Creates a {@link YrestServer} from an already-initialised storage and parsed options.
@@ -642,4 +746,32 @@ declare function createYrestServer(options: YrestServerOptions): YrestServer;
 
 declare function createYrestStorage(filePath: string): YrestStorage;
 
-export { type CustomRoute, type Data, type Handler, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type YrestOptions, type YrestServer, type YrestServerBaseOptions, type YrestServerOptions, type YrestStorage, createServer, createYrestServer, createYrestServerFromStorage, createYrestStorage, yrest, yrestOptionsSchema };
+/** Input for {@link generateTypes}: the parsed pieces of a `db.yml` file. */
+type GenerateTypesInput = {
+    /** Collections and their items. */
+    data: Data;
+    /** Field-level declarations from `_schema` (optional). */
+    schema?: SchemaBlock;
+    /** Relations from `_rel` — used to annotate FK fields (optional). */
+    relations?: Relations;
+};
+/** Options for {@link generateTypes}. */
+type GenerateTypesOptions = {
+    /** Source file name shown in the header comment (e.g. `"db.yml"`). */
+    source?: string;
+};
+/**
+ * Generates TypeScript declarations from a yrest dataset.
+ *
+ * - One `interface` per collection, named in singular PascalCase (`post_tags` → `PostTag`).
+ * - Types are inferred from **all** items; a field missing on any item is optional.
+ * - `_schema` declarations override inference (`_type`, `_required`, `_enum`, `_nullable`, `_items`)
+ *   and add JSDoc (`_description`, `_format`, `_deprecated`).
+ * - `_rel` many2one/one2one FK fields get a `FK → target.id` JSDoc note.
+ * - Ends with a `CollectionName` union and a `Collections` map (`{ users: User[] }`).
+ *
+ * Output is deterministic: collections and fields keep their order of appearance.
+ */
+declare function generateTypes(input: GenerateTypesInput, options?: GenerateTypesOptions): string;
+
+export { type CollectionAccessor, type CollectionHandle, type CustomRoute, type Data, type GenerateTypesInput, type GenerateTypesOptions, type Handler, type HandlerContext, type HandlerMap, type HandlerRequest, type HandlerResponse, type Relations, type Resource, type SseHandler, type YrestOptions, type YrestServer, type YrestServerBaseOptions, type YrestServerOptions, type YrestStorage, createServer, createYrestServer, createYrestServerFromStorage, createYrestStorage, defineHandler, defineSseHandler, generateTypes, yrest, yrestOptionsSchema };