@trpc-panel/core 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# tRPC.panel()
+
+Probably the easiest and cheapest way to build a testing UI and documentation for your tRPC endpoints. tRPC panel automatically generates a UI for manually testing your tRPC backend with 0 overhead:
+
+![Screenshot 2022-12-08 at 7 24 02 PM](https://user-images.githubusercontent.com/12774588/206602120-017a2b3a-66c3-4bf0-bd93-90fb4bddf0cc.png)
+
+trpc panel moves as fast as your trpc backend with minimal effort.
+
+Check out our [test app](https://app.trpcpanel.io)
+
+## Features
+
+- 🚀 Automatically inspect your tRPC router and recursively generate a typesafe UI
+- 🕒 Zero overhead
+  - No output schemas (procedure return types can be inferred as nature intended)
+  - New procedures will be added to your UI as you create them in your backend
+  - No compilation required, works with any backend
+- 📄 [Document](#documenting-procedures) your procedures and input parameters with minimal effort
+- 🐦 Supports nested routers, and nested input objects. The structure of the UI maps one-to-one to your API's routers and procedures.
+- 🧭 SideNav and VSCode-like procedure / router search to quickly find what you're looking for
+- ✨ [Transform](#data-transformers) data with built in `superjson` support.
+
+## Quick Start
+
+Install with your preferred package manager:
+
+```sh
+yarn add trpc-panel
+```
+
+render your panel and return it from your backend (express example):
+
+```js
+import { renderTrpcPanel } from "trpc-panel";
+// ...
+app.use("/panel", (_, res) => {
+  return res.send(
+    renderTrpcPanel(myTrpcRouter, { url: "http://localhost:4000/trpc" })
+  );
+});
+```
+
+`trpc-panel` just renders as a string, so it can be used with any backend.
+
+## NextJS / create-t3-app example
+
+In Nextjs you'd want to create an api route somewhere like `src/pages/api/panel.ts` and send a text response:
+
+```ts
+import type { NextApiRequest, NextApiResponse } from "next";
+import { renderTrpcPanel } from "trpc-panel";
+import { appRouter } from "../../server/api/root";
+
+export default async function handler(_: NextApiRequest, res: NextApiResponse) {
+  res.status(200).send(
+    renderTrpcPanel(appRouter, {
+      url: "http://localhost:3000/api/trpc",
+      transformer: "superjson",
+    })
+  );
+}
+```
+
+Then we can visit the url `http://localhost:3000/api/panel` to use the panel. Here we do `transformer: "superjson"` assuming we have `superjson` set as the transformer in tRPC (which create-t3-app does by default).
+
+## Documenting Procedures
+
+As of v1.1.0, `trpc-panel` supports documenting procedures.
+
+Documentation is opt-in, meaning you only need to set it up if you want to use it. When docs are included for your trpc procedure, a "Docs" section will appear in your procedure:
+
+![Documentation Example](https://user-images.githubusercontent.com/12774588/208321430-6fea4c92-b0a9-4d9c-a95e-6bf5af04823b.png)
+
+### Procedure Descriptions
+
+`trpc-panel` supports documenting procedures via trpc meta. First setup your trpc instance to be typed with `TRPCPanelMeta`:
+
+```ts
+import { initTRPC } from "@trpc/server";
+import { TRPCPanelMeta } from "trpc-panel";
+
+const t = initTRPC.meta<TRPCPanelMeta>().create();
+```
+
+Then in your routers you can provide a description to the meta:
+
+```ts
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .meta({ /* 👉 */ description: "This shows in the panel." })
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => {
+      return { greeting: `Hello ${input.name}!` };
+    });
+});
+```
+
+### Input Parameter Descriptions
+
+`trpc-panel` supports documenting parameters via zod's `.describe()` method. This allows developers to quickly write documentation as they're writing schemas:
+
+```ts
+export const appRouter = t.router({
+  sayHello: t.procedure
+    .input(z.object({
+        name: z.string().describe("The name to say hello too.")
+    }))
+    .query(({ input }) => {
+      return { greeting: `Hello ${input.name}!` };
+    });
+});
+```
+
+Whatever you pass to `describe()` will appear in the docs section. Any input fields without a description will not appear in the docs section.
+
+## Data Transformers
+
+Trpc panel supports `superjson`, just pass it into the transformer option:
+
+```js
+app.use("/panel", (_, res) => {
+  return res.send(
+    renderTrpcPanel(myTrpcRouter, {
+      url: "http://localhost:4000/trpc",
+      transformer: "superjson",
+    })
+  );
+});
+```
+
+## Contributing
+
+`trpc-panel` welcomes and encourages open source contributions. Please see our [contributing](./CONTRIBUTING.md) guide for information on how to develop locally.
+
+## Limitations
+
+Currently, tRPC panel supports tRPC v10 and v11 and only works with zod input schemas. With it's current design it would be feasible to easily add support for other input types as well
+
+There are no plans to support v9 or other previous tRPC versions.
+
+### Supported zod types
+
+The following are supported
+
+- Array
+- BigInt
+- Boolean
+- Branded
+- Default
+- DiscriminatedUnion
+- Effects
+- Enum
+- Literal
+- Nullable
+- Null
+- Nullish
+- Number
+- Object
+- Optional
+- Promise
+- String
+- Undefined
+
+We would like to add the following types:
+
+- Union
+- Tuple
+- Record
+- Never
+- Map (superjson only)
+- Set (superjson only)
+- Date (superjson only)
+- Any

package/lib/index.js

@@ -0,0 +1,431 @@
+'use strict';
+
+var fs = require('fs');
+var node_url = require('node:url');
+var node_path = require('node:path');
+var zod = require('zod');
+var zodToJsonSchema = require('zod-to-json-schema');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const TRPCPanelMetaSchema = zod.z.object({
+    description: zod.z.string().optional(),
+});
+
+zod.z.object({});
+const SharedProcedureDefPropertiesSchema = zod.z.object({
+    inputs: zod.z.unknown().array().optional(),
+    input: zod.z.unknown().optional(),
+    meta: TRPCPanelMetaSchema.optional(),
+});
+const QueryDefSchema = SharedProcedureDefPropertiesSchema.and(zod.z.union([
+    zod.z.object({
+        query: zod.z.literal(true),
+    }),
+    zod.z.object({
+        type: zod.z.literal("query"),
+    }),
+]));
+function isQueryDef(obj) {
+    return QueryDefSchema.safeParse(obj).success;
+}
+const MutationDefSchema = SharedProcedureDefPropertiesSchema.and(zod.z.union([
+    zod.z.object({
+        mutation: zod.z.literal(true),
+    }),
+    zod.z.object({
+        type: zod.z.literal("mutation"),
+    }),
+]));
+function isMutationDef(obj) {
+    return MutationDefSchema.safeParse(obj).success;
+}
+const SubscriptionDefSchema = SharedProcedureDefPropertiesSchema.and(zod.z.union([
+    zod.z.object({
+        subscription: zod.z.literal(true),
+    }),
+    zod.z.object({
+        type: zod.z.literal("subscription"),
+    }),
+]));
+function isSubscriptionDef(obj) {
+    return SubscriptionDefSchema.safeParse(obj).success;
+}
+const ProcedureDefSchema = QueryDefSchema.or(MutationDefSchema).or(SubscriptionDefSchema);
+const RouterDefSchema = zod.z.object({
+    router: zod.z.literal(true).optional(),
+    type: zod.z.undefined(),
+    query: zod.z.undefined(),
+    mutation: zod.z.undefined(),
+    subscription: zod.z.undefined(),
+    inputs: zod.z.undefined(),
+    input: zod.z.undefined(),
+});
+const RouterSchema = zod.z.object({
+    _def: RouterDefSchema,
+});
+function isRouter(obj) {
+    return RouterSchema.safeParse(obj).success;
+}
+zod.z.object({
+    _def: ProcedureDefSchema,
+});
+function isProcedure(obj) {
+    if (typeof obj !== "function" || !("_def" in obj))
+        return false;
+    return ProcedureDefSchema.safeParse(obj._def).success;
+}
+zod.z.object({
+    _def: QueryDefSchema,
+});
+
+function logParseError(procedurePath, error) {
+    console.warn(`trpc-panel: Failed to parse procedure ${procedurePath}, ${error}`);
+}
+
+function nodePropertiesFromRef(references) {
+    return Object.assign({ path: references.path }, (references.optional && { optional: true }));
+}
+
+const parseZodStringDef = (def, refs) => {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "string" }, nodePropertiesFromRef(refs));
+};
+
+const parseZodArrayDef = (def, refs) => {
+    const { type } = def;
+    const childType = zodSelectorFunction(type._def, Object.assign(Object.assign({}, refs), { path: [] }));
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "array", childType }, nodePropertiesFromRef(refs));
+};
+
+const parseZodBooleanFieldDef = (def, refs) => {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "boolean" }, nodePropertiesFromRef(refs));
+};
+
+function isZodThreePointTwenty(def) {
+    return "optionsMap" in def;
+}
+function makeDefConsistent(def) {
+    const optionsMap = isZodThreePointTwenty(def) ? def.optionsMap : def.options;
+    return {
+        typeName: zod.ZodFirstPartyTypeKind.ZodDiscriminatedUnion,
+        discriminator: def.discriminator,
+        options: optionsMap,
+    };
+}
+const parseZodDiscriminatedUnionDef = (def, refs) => {
+    const defConsistent = makeDefConsistent(def);
+    const entries = Array.from(defConsistent.options.entries());
+    const nodeEntries = entries.map(([discriminatorValue, zodObj]) => [
+        discriminatorValue,
+        zodSelectorFunction(zodObj._def, refs),
+    ]);
+    const nodesMap = Object.fromEntries(nodeEntries);
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "discriminated-union", discriminatedUnionValues: entries.map(([n]) => n), discriminatedUnionChildrenMap: nodesMap, discriminatorName: def.discriminator }, nodePropertiesFromRef(refs));
+};
+
+const parseZodEnumDef = (def, refs) => {
+    const values = def.values;
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "enum", enumValues: values }, nodePropertiesFromRef(refs));
+};
+
+const parseZodLiteralDef = (def, refs) => {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "literal", value: def.value }, nodePropertiesFromRef(refs));
+};
+
+const parseZodNumberDef = (def, refs) => {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "number" }, nodePropertiesFromRef(refs));
+};
+
+const parseZodObjectDef = (def, refs) => {
+    const shape = def.shape();
+    const children = {};
+    for (var propertyName of Object.keys(shape)) {
+        const node = zodSelectorFunction(shape[propertyName]._def, Object.assign(Object.assign({}, refs), { path: refs.path.concat([propertyName]) }));
+        children[propertyName] = node;
+    }
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "object", children }, nodePropertiesFromRef(refs));
+};
+
+const parseZodOptionalDef = (def, refs) => {
+    const parsedInner = zodSelectorFunction(def.innerType._def, refs);
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign(Object.assign({}, parsedInner), { optional: true });
+};
+
+function parseZodNullableDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return zodSelectorFunction(def.innerType._def, refs);
+}
+
+function parseZodBigIntDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "number" }, nodePropertiesFromRef(refs));
+}
+
+function parseZodBrandedDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return zodSelectorFunction(def.type._def, refs);
+}
+
+function parseZodDefaultDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return zodSelectorFunction(def.innerType._def, refs);
+}
+
+function parseZodEffectsDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return zodSelectorFunction(def.schema._def, refs);
+}
+
+function parseZodNullDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "literal", value: null }, nodePropertiesFromRef(refs));
+}
+
+function parseZodPromiseDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return zodSelectorFunction(def.type._def, refs);
+}
+
+function parseZodUndefinedDef(def, refs) {
+    refs.addDataFunctions.addDescriptionIfExists(def, refs);
+    return Object.assign({ type: "literal", value: undefined }, nodePropertiesFromRef(refs));
+}
+
+function parseZodVoidDef(_, refs) {
+    return {
+        type: "literal",
+        value: undefined,
+        path: refs.path,
+    };
+}
+
+const zodSelectorFunction = (def, references) => {
+    switch (def.typeName) {
+        case zod.ZodFirstPartyTypeKind.ZodArray:
+            return parseZodArrayDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodBoolean:
+            return parseZodBooleanFieldDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodDiscriminatedUnion:
+            return parseZodDiscriminatedUnionDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodEnum:
+            return parseZodEnumDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodLiteral:
+            return parseZodLiteralDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodNumber:
+            return parseZodNumberDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodObject:
+            return parseZodObjectDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodOptional:
+            return parseZodOptionalDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodString:
+            return parseZodStringDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodNullable:
+            return parseZodNullableDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodBigInt:
+            return parseZodBigIntDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodBranded:
+            return parseZodBrandedDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodDefault:
+            return parseZodDefaultDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodEffects:
+            return parseZodEffectsDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodNull:
+            return parseZodNullDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodPromise:
+            return parseZodPromiseDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodUndefined:
+            return parseZodUndefinedDef(def, references);
+        case zod.ZodFirstPartyTypeKind.ZodVoid:
+            return parseZodVoidDef(def, references);
+    }
+    return { type: "unsupported", path: references.path };
+};
+
+const inputParserMap = {
+    zod: (zodObject, refs) => {
+        return zodSelectorFunction(zodObject._def, refs);
+    },
+};
+const emptyZodObject = zod.z.object({});
+function nodeAndInputSchemaFromInputs(inputs, _routerPath, options, addDataFunctions) {
+    if (!inputs.length) {
+        return {
+            parseInputResult: "success",
+            schema: zodToJsonSchema.zodToJsonSchema(emptyZodObject, {
+                errorMessages: true,
+                $refStrategy: "none",
+                target: "jsonSchema7"
+            }),
+            node: inputParserMap["zod"](emptyZodObject, {
+                path: [],
+                options,
+                addDataFunctions,
+            }),
+        };
+    }
+    if (inputs.length !== 1) {
+        return { parseInputResult: "failure" };
+    }
+    const input = inputs[0];
+    return {
+        parseInputResult: "success",
+        schema: zodToJsonSchema.zodToJsonSchema(input, {
+            errorMessages: true,
+            $refStrategy: "none",
+            target: "jsonSchema7"
+        }),
+        node: zodSelectorFunction(input._def, {
+            path: [],
+            options,
+            addDataFunctions,
+        }),
+    };
+}
+function parseProcedure(procedure, path, options) {
+    var _a, _b;
+    const { _def } = procedure;
+    const inputs = (_a = _def.inputs) !== null && _a !== void 0 ? _a : (_def.input ? [_def.input] : []);
+    const parseExtraData = {
+        parameterDescriptions: {},
+    };
+    const nodeAndInput = nodeAndInputSchemaFromInputs(inputs, path, options, {
+        addDescriptionIfExists: (def, refs) => {
+            if (def.description) {
+                parseExtraData.parameterDescriptions[refs.path.join(".")] =
+                    def.description;
+            }
+        },
+    });
+    if (nodeAndInput.parseInputResult === "failure") {
+        return null;
+    }
+    const t = (() => {
+        if (isQueryDef(_def))
+            return "query";
+        if (isMutationDef(_def))
+            return "mutation";
+        if (isSubscriptionDef(_def))
+            return "subscription";
+        return null;
+    })();
+    if (!t) {
+        return null;
+    }
+    return {
+        inputSchema: nodeAndInput.schema,
+        node: nodeAndInput.node,
+        nodeType: "procedure",
+        procedureType: t,
+        pathFromRootRouter: path,
+        extraData: Object.assign(Object.assign({}, parseExtraData), (((_b = procedure._def.meta) === null || _b === void 0 ? void 0 : _b.description) && {
+            description: procedure._def.meta.description,
+        })),
+    };
+}
+
+const skipSet = new Set(["createCaller", "_def", "getErrorShape"]);
+function parseRouter(router, routerPath, options) {
+    const children = {};
+    var hasChild = false;
+    for (var [procedureOrRouterPath, child] of Object.entries(router)) {
+        if (skipSet.has(procedureOrRouterPath))
+            continue;
+        const newPath = routerPath.concat([procedureOrRouterPath]);
+        const parsedNode = (() => {
+            if (isRouter(child)) {
+                return parseRouter(child, newPath, options);
+            }
+            if (isProcedure(child)) {
+                return parseProcedure(child, newPath, options);
+            }
+            return null;
+        })();
+        if (!parsedNode) {
+            logParseError(newPath.join("."), "Couldn't parse node.");
+            continue;
+        }
+        hasChild = true;
+        children[procedureOrRouterPath] = parsedNode;
+    }
+    if (!hasChild)
+        logParseError(routerPath.join("."), `Router doesn't have any successfully parsed children.`);
+    return { children, nodeType: "router", path: routerPath };
+}
+function parseRouterWithOptions(router, parseRouterOptions) {
+    if (!isRouter(router)) {
+        throw new Error("Non trpc router passed to trpc panel.");
+    }
+    return parseRouter(router, [], parseRouterOptions);
+}
+
+const defaultParseRouterOptions = {
+    logFailedProcedureParse: true,
+    transformer: "superjson",
+};
+const __dirname$1 = node_path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href))));
+const javascriptReplaceSymbol = "{{js}}";
+const cssReplaceSymbol = "{{css}}";
+const routerReplaceSymbol = '"{{parsed_router}}"';
+const optionsReplaceSymbol = '"{{options}}"';
+const bundlePath = __dirname$1 + "/react-app/bundle.js";
+const indexPath = __dirname$1 + "/react-app/index.html";
+const cssPath = __dirname$1 + "/react-app/index.css";
+const bundleJs = fs.readFileSync(bundlePath).toString();
+const indexHtml = fs.readFileSync(indexPath).toString();
+const indexCss = fs.readFileSync(cssPath).toString();
+function injectParams(string, injectionParams) {
+    var r = string;
+    for (var param of injectionParams) {
+        r = injectInString(param.searchFor, r, param.injectString);
+    }
+    return r;
+}
+function injectInString(searchFor, string, injectString) {
+    const startIndex = string.indexOf(searchFor);
+    return (string.slice(0, startIndex) +
+        injectString +
+        string.slice(startIndex + searchFor.length));
+}
+let cache = {
+    val: null,
+};
+function renderTrpcPanel(router, options) {
+    if (options.cache === true && cache.val)
+        return cache.val;
+    const bundleInjectionParams = [
+        {
+            searchFor: routerReplaceSymbol,
+            injectString: JSON.stringify(parseRouterWithOptions(router, Object.assign(Object.assign({}, defaultParseRouterOptions), options))),
+        },
+        {
+            searchFor: optionsReplaceSymbol,
+            injectString: JSON.stringify(options),
+        },
+    ];
+    const bundleInjected = injectParams(bundleJs, bundleInjectionParams);
+    const script = `<script>${bundleInjected}</script>`;
+    const css = `<style>${indexCss}</style>`;
+    const htmlReplaceParams = [
+        {
+            searchFor: javascriptReplaceSymbol,
+            injectString: script,
+        },
+        {
+            searchFor: cssReplaceSymbol,
+            injectString: css,
+        },
+    ];
+    cache.val = injectParams(indexHtml, htmlReplaceParams);
+    return cache.val;
+}
+
+exports.parseRouterWithOptions = parseRouterWithOptions;
+exports.renderTrpcPanel = renderTrpcPanel;