@emeryld/rrroutes-contract 2.7.0 → 2.7.1

package/README.md

@@ -299,3 +299,77 @@ pnpm --filter @emeryld/rrroutes-contract build    # tsup + d.ts
 pnpm --filter @emeryld/rrroutes-contract typecheck
 pnpm --filter @emeryld/rrroutes-contract test     # optional Jest suite
 ```
+
+## Finalized Leaves Export (JSON)
+
+You can export finalized leaves (plus flattened schema paths) to strict JSON.
+
+### What `--module` means
+
+`--module` is the path to a JS/TS module file that **exports** your leaves or registry.
+
+- The file can export:
+  - a finalized registry (`finalize(leaves)`)
+  - or a leaf array/tuple (the output of `.done()`)
+- Use `--export` to select which exported symbol to read from that module.
+
+### CLI usage
+
+From the repo root:
+
+```sh
+pnpm --filter @emeryld/rrroutes-contract export:finalized-leaves -- \
+  --module ./path/to/contract-module.ts \
+  --export registry \
+  --out ./finalized-leaves.export.json
+```
+
+Arguments:
+
+- `--module` required path to the module that exports your data.
+- `--export` optional export name (default: `leaves`).
+- `--out` optional output file path (default: `finalized-leaves.export.json`).
+
+### Example module shapes
+
+Registry export:
+
+```ts
+import { finalize, resource } from '@emeryld/rrroutes-contract'
+import { z } from 'zod'
+
+const leaves = resource('/v1')
+  .get({ outputSchema: z.object({ ok: z.literal(true) }) })
+  .done()
+
+export const registry = finalize(leaves)
+```
+
+Leaves export:
+
+```ts
+import { resource } from '@emeryld/rrroutes-contract'
+import { z } from 'zod'
+
+export const leaves = resource('/v1')
+  .get({ outputSchema: z.object({ ok: z.literal(true) }) })
+  .done()
+```
+
+### Runtime API
+
+If you want to run this in code instead of CLI:
+
+```ts
+import { exportFinalizedLeaves } from '@emeryld/rrroutes-contract'
+
+const payload = await exportFinalizedLeaves(registry, {
+  outFile: './finalized-leaves.export.json',
+})
+```
+
+`payload` contains:
+
+- `_meta`: export/documentation metadata
+- `leaves`: contract-native serialized leaves
+- `schemaFlatByLeaf`: flattened schema map per leaf

package/dist/export/exportFinalizedLeaves.cli.d.ts

@@ -0,0 +1,12 @@
+import { type ExportFinalizedLeavesInput } from './exportFinalizedLeaves';
+export type FinalizedLeavesCliArgs = {
+    modulePath: string;
+    exportName: string;
+    outFile: string;
+};
+export declare function parseFinalizedLeavesCliArgs(argv: string[]): FinalizedLeavesCliArgs;
+export declare function loadFinalizedLeavesInput({ modulePath, exportName, }: FinalizedLeavesCliArgs): Promise<ExportFinalizedLeavesInput>;
+export declare function runExportFinalizedLeavesCli(argv: string[]): Promise<{
+    payload: import("./exportFinalizedLeaves").FinalizedLeavesExport;
+    outFile: string;
+}>;

package/dist/export/exportFinalizedLeaves.d.ts

@@ -0,0 +1,30 @@
+import type { AnyLeafLowProfile } from '../core/routesV3.core';
+import type { FinalizedRegistry } from '../core/routesV3.finalize';
+import { type FlatSchemaMap } from './flattenSchema';
+import { type SerializeLeafContractOptions, type SerializedLeafContract } from './serializeLeafContract';
+export type ExportFinalizedLeavesInput = readonly AnyLeafLowProfile[] | FinalizedRegistry<readonly AnyLeafLowProfile[]>;
+export type ExportFinalizedLeavesMeta = {
+    generatedAt: string;
+    description: string;
+    fieldCatalog: {
+        leaf: string[];
+        cfg: string[];
+        schemaNode: string[];
+        flatSchemaEntry: string[];
+    };
+    flattening: {
+        notation: 'dot+[]';
+        unionBranchSuffix: '-N';
+        sections: readonly ['params', 'query', 'body', 'output'];
+    };
+};
+export type FinalizedLeavesExport = {
+    _meta: ExportFinalizedLeavesMeta;
+    leaves: SerializedLeafContract[];
+    schemaFlatByLeaf: Record<string, FlatSchemaMap>;
+};
+export type ExportFinalizedLeavesOptions = SerializeLeafContractOptions & {
+    outFile?: string;
+};
+export declare function writeFinalizedLeavesExport(payload: FinalizedLeavesExport, outFile: string): Promise<string>;
+export declare function exportFinalizedLeaves(input: ExportFinalizedLeavesInput, options?: ExportFinalizedLeavesOptions): Promise<FinalizedLeavesExport>;

package/dist/export/flattenSchema.d.ts

@@ -0,0 +1,11 @@
+import type { AnyLeafLowProfile } from '../core/routesV3.core';
+import { type SerializedLeafContract } from './serializeLeafContract';
+import type { SerializableSchema } from './schemaIntrospection';
+export type FlatSchemaEntry = {
+    type: string;
+    nullable: boolean;
+    optional: boolean;
+};
+export type FlatSchemaMap = Record<string, FlatSchemaEntry>;
+export declare function flattenSerializableSchema(schema: SerializableSchema | undefined, path: string): FlatSchemaMap;
+export declare function flattenLeafSchemas(leaf: AnyLeafLowProfile | SerializedLeafContract): FlatSchemaMap;

package/dist/export/index.d.ts

@@ -0,0 +1,5 @@
+export * from './schemaIntrospection';
+export * from './serializeLeafContract';
+export * from './flattenSchema';
+export * from './exportFinalizedLeaves';
+export * from './exportFinalizedLeaves.cli';

package/dist/export/schemaIntrospection.d.ts

@@ -0,0 +1,47 @@
+import * as z from 'zod';
+export declare const serializableSchemaKinds: readonly ["object", "string", "number", "boolean", "bigint", "date", "array", "enum", "literal", "union", "record", "tuple", "unknown", "any"];
+export type SerializableSchemaKind = (typeof serializableSchemaKinds)[number];
+export type SerializableSchema = {
+    kind: SerializableSchemaKind;
+    optional?: boolean;
+    nullable?: boolean;
+    description?: string;
+    properties?: Record<string, SerializableSchema>;
+    element?: SerializableSchema;
+    union?: SerializableSchema[];
+    literal?: unknown;
+    enumValues?: string[];
+};
+type ZodAny = z.ZodTypeAny;
+type InternalSchemaKind = SerializableSchemaKind | 'intersection';
+type IntrospectionWalker = (schema: ZodAny | undefined) => SerializableSchema | undefined;
+export type IntrospectionContext = {
+    zod: typeof z;
+    introspect: IntrospectionWalker;
+    getDef: (schema: unknown) => any | undefined;
+    unwrap: (schema: ZodAny) => {
+        base: ZodAny;
+        optional: boolean;
+        nullable: boolean;
+    };
+    getDescription: (schema: ZodAny) => string | undefined;
+};
+export type IntrospectionNode = {
+    schema: ZodAny;
+    base: ZodAny;
+    def: any;
+    kind: InternalSchemaKind;
+    optional: boolean;
+    nullable: boolean;
+    node: SerializableSchema;
+};
+export type SchemaIntrospectionHandler = (args: IntrospectionNode, ctx: IntrospectionContext) => SerializableSchema | undefined;
+export type SchemaIntrospectionHandlerMap = Partial<Record<InternalSchemaKind, SchemaIntrospectionHandler>>;
+export type IntrospectSchemaOptions = {
+    handlers?: SchemaIntrospectionHandlerMap;
+};
+export declare function registerSchemaIntrospectionHandler(kind: InternalSchemaKind, handler: SchemaIntrospectionHandler): void;
+export declare function clearSchemaIntrospectionHandlers(): void;
+export declare function createSchemaIntrospector(options?: IntrospectSchemaOptions): IntrospectionWalker;
+export declare function introspectSchema(schema: ZodAny | undefined, options?: IntrospectSchemaOptions): SerializableSchema | undefined;
+export {};

package/dist/export/serializeLeafContract.d.ts

@@ -0,0 +1,31 @@
+import { type AnyLeafLowProfile, type FileField } from '../core/routesV3.core';
+import { type IntrospectSchemaOptions, type SerializableSchema } from './schemaIntrospection';
+export type ContractLeafSchemas = {
+    body?: SerializableSchema;
+    query?: SerializableSchema;
+    params?: SerializableSchema;
+    output?: SerializableSchema;
+    outputMeta?: SerializableSchema;
+    queryExtension?: SerializableSchema;
+};
+export type SerializedLeafContract = {
+    key: string;
+    method: AnyLeafLowProfile['method'];
+    path: string;
+    cfg: {
+        description?: string;
+        summary?: string;
+        docsGroup?: string;
+        tags?: string[];
+        deprecated?: boolean;
+        stability?: 'experimental' | 'beta' | 'stable' | 'deprecated';
+        docsHidden?: boolean;
+        docsMeta?: Record<string, unknown>;
+        feed?: boolean;
+        bodyFiles?: FileField[];
+        schemas: ContractLeafSchemas;
+    };
+};
+export type SerializeLeafContractOptions = IntrospectSchemaOptions;
+export declare function serializeLeafContract(leaf: AnyLeafLowProfile, options?: SerializeLeafContractOptions): SerializedLeafContract;
+export declare function serializeLeavesContract(leaves: readonly AnyLeafLowProfile[], options?: SerializeLeafContractOptions): SerializedLeafContract[];