@emeryld/rrroutes-contract 2.6.6 → 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/core/routesV3.core.d.ts

@@ -19,11 +19,12 @@ export interface NodeCfg {
      */
     outputMetaSchema?: ZodType;
 }
-export type RouteSchema<Output = unknown, Input = unknown> = {
+export type RouteSchema<Output = unknown, Input = unknown, Schema extends ZodType<Output, Input> = ZodType<Output, Input>> = {
     __out: Output;
     __in?: Input;
+    __zod?: Schema;
 };
-type RouteSchemaOrUndefined<S extends ZodType | undefined> = S extends ZodType<infer Out, infer In> ? RouteSchema<Out, In> : undefined;
+type RouteSchemaOrUndefined<S extends ZodType | undefined> = S extends ZodType<infer Out, infer In> ? RouteSchema<Out, In, S> : undefined;
 type FeedAwareQueryRoute<Feed extends boolean, Query extends ZodType | undefined, Extension extends ZodType | undefined, Node extends NodeCfg | undefined> = Feed extends true ? ToRouteSchema<FeedQueryField<{
     querySchema: Query;
     queryExtensionSchema: EffectiveQueryExtensionSchema<Extension, Node>;
@@ -49,9 +50,12 @@ export type RouteSchemaOutput<Schema extends RouteSchema> = Schema extends {
 export type RouteSchemaInput<Schema extends RouteSchema> = Schema extends {
     __in?: infer In;
 } ? In : unknown;
+type RouteSchemaZod<Schema extends RouteSchema> = Schema extends {
+    __zod?: infer SchemaType extends ZodType;
+} ? SchemaType : ZodType<RouteSchemaOutput<Schema>, RouteSchemaInput<Schema>>;
 export declare const lowProfileParse: <T extends RouteSchema>(schema: T, data: unknown) => RouteSchemaOutput<T>;
 export declare const lowProfileSafeParse: <T extends RouteSchema>(schema: T, data: unknown) => ZodSafeParseResult<RouteSchemaOutput<T>>;
-export declare const routeSchemaParse: <T>(routeSchema: RouteSchema<T>) => ZodType<T>;
+export declare const routeSchemaParse: <S extends RouteSchema>(routeSchema: S) => RouteSchemaZod<S>;
 /**
  * Runtime helper that mirrors the typed merge used by the builder.
  * @param a Previously merged params schema inherited from parent segments.
@@ -61,7 +65,7 @@ export declare const routeSchemaParse: <T>(routeSchema: RouteSchema<T>) => ZodTy
 export declare function mergeSchemas<A extends ZodType | undefined, B extends ZodType | undefined>(a: A, b: B): IntersectZod<A, B>;
 export declare function getZodShape(schema: ZodObject): any;
 export declare function collectNestedFieldSuggestions(shape: Record<string, ZodType> | undefined, prefix?: string[]): string[];
-export type ToRouteSchema<S> = S extends ZodType<infer Out, infer In> ? RouteSchema<Out, In> : S;
+export type ToRouteSchema<S> = S extends ZodType<infer Out, infer In> ? RouteSchema<Out, In, S> : S;
 export type LowProfileCfg<Cfg extends MethodCfg = MethodCfg> = Prettify<Omit<Cfg, 'bodySchema' | 'querySchema' | 'paramsSchema' | 'outputSchema' | 'outputMetaSchema'> & {
     bodySchema: ToRouteSchema<Cfg['bodySchema']>;
     querySchema: ToRouteSchema<Cfg['querySchema']>;

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[];