@sapporta/rest-open-api 3.52.1

package/src/lib/parsers/path-params.spec.ts

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+import { ZOD_SYNC, ZOD_ASYNC } from './test-helpers';
+import { getParamsFromPathOnly, getPathParameterSchema } from './path-params';
+import { ParameterObject } from 'openapi3-ts';
+import { ContractAnyType } from '@sapporta/rest-core';
+
+/**
+ * Theres a few permutations to deal with, mainly sync and async, so we build up CASES then run them against both
+ */
+const CASES: {
+  type: 'zod';
+  name: string;
+  path: string;
+  pathParams: unknown;
+  expected: ParameterObject[];
+  only?: true;
+}[] = [
+  {
+    type: 'zod',
+    name: 'no params, no schema',
+    path: '/',
+    pathParams: undefined,
+    expected: [],
+  },
+  {
+    type: 'zod',
+    name: 'single param, no schema',
+    path: '/:id',
+    pathParams: undefined,
+    expected: [
+      {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+  {
+    type: 'zod',
+    name: 'multiple params, no schema',
+    pathParams: undefined,
+    path: '/:id/:name',
+    expected: [
+      {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+      {
+        name: 'name',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+  {
+    type: 'zod',
+    name: 'single param, zod schema',
+    path: '/:id',
+    pathParams: z.object({
+      id: z.string().describe('The id of the post'),
+    }),
+    expected: [
+      {
+        name: 'id',
+        description: 'The id of the post',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+  {
+    type: 'zod',
+    name: 'multiple params, zod schema',
+    path: '/:id/:name',
+    pathParams: z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+    expected: [
+      {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+      {
+        name: 'name',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+  {
+    type: 'zod',
+    name: 'multiple params, partial zod schema',
+    path: '/:id/:name/:extra',
+    pathParams: z.object({
+      id: z.string().optional(),
+      name: z.string().optional(),
+      // extra is not in the schema
+    }),
+    expected: [
+      {
+        name: 'id',
+        in: 'path',
+        schema: {
+          type: 'string',
+        },
+      },
+      {
+        name: 'name',
+        in: 'path',
+        schema: {
+          type: 'string',
+        },
+      },
+      {
+        name: 'extra',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+  {
+    type: 'zod',
+    name: 'single param, zod schema, optional',
+    path: '/:id',
+    pathParams: z.object({
+      id: z.string().optional(),
+    }),
+    expected: [
+      {
+        name: 'id',
+        in: 'path',
+        schema: {
+          type: 'string',
+        },
+      },
+    ],
+  },
+];
+
+const hasOnly = CASES.some((c) => c.only);
+const CASES_TO_RUN = hasOnly ? CASES.filter((c) => c.only) : CASES;
+
+describe('path-params', () => {
+  it.each(CASES_TO_RUN)(
+    'sync - $name ($type)',
+    ({ type, name, path, pathParams, expected }) => {
+      const res = getPathParameterSchema.sync({
+        transformSchema: ZOD_SYNC,
+        appRoute: {
+          method: 'GET',
+          path,
+          pathParams: pathParams as ContractAnyType | undefined,
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(res).toEqual(expected);
+    },
+  );
+
+  it.each(CASES_TO_RUN)(
+    'async - $name ($type)',
+    async ({ type, name, path, pathParams, expected }) => {
+      const res = await getPathParameterSchema.async({
+        transformSchema: ZOD_ASYNC,
+        appRoute: {
+          method: 'GET',
+          path,
+          pathParams: pathParams as ContractAnyType | undefined,
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(res).toEqual(expected);
+    },
+  );
+});
+
+describe('getParamsFromPathOnly', () => {
+  it('should return the correct params', () => {
+    const params = getParamsFromPathOnly('/posts/:id/comments/:commentId');
+    const paramsArray = Array.from(params.values());
+
+    expect(paramsArray).toEqual([
+      {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      },
+      {
+        name: 'commentId',
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      },
+    ]);
+  });
+});

package/src/lib/parsers/path-params.ts

@@ -0,0 +1,140 @@
+import { AppRoute } from '@sapporta/rest-core';
+import {
+  AsyncAndSyncHelper,
+  GetAsyncFunction,
+  GetSyncFunction,
+  SchemaTransformerAsync,
+  SchemaTransformerSync,
+} from '../types';
+import { ParameterObject } from 'openapi3-ts';
+import { schemaObjectToParameters } from './utils';
+
+type GetPathParameterHelper = AsyncAndSyncHelper<
+  {
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+  },
+  {
+    transformSchema: SchemaTransformerSync;
+  },
+  {
+    transformSchema: SchemaTransformerAsync;
+  },
+  Array<ParameterObject>
+>;
+
+/**
+ * We build up the params from both the path and the schema.
+ *
+ * This builds up the record of name -> parameter object.
+ */
+export const getParamsFromPathOnly = (
+  path: string,
+): Map<string, ParameterObject> => {
+  const params = new Map<string, ParameterObject>();
+
+  const paramsInPath =
+    path.match(/:([^/]+)/g)?.map((param) => param.slice(1)) || [];
+
+  for (const param of paramsInPath) {
+    params.set(param, {
+      name: param,
+      in: 'path' as const,
+      required: true,
+      schema: { type: 'string' },
+    });
+  }
+
+  return params;
+};
+
+/**
+ * Should return schema params as priority, and then path params as fallback
+ *
+ * @param pathParams - params inferred from the path i.e. just from the string
+ * @param schemaParams - params from the schema
+ */
+const mergeParams = (
+  pathParams: Map<string, ParameterObject>,
+  schemaParams: Map<string, ParameterObject>,
+): Array<ParameterObject> => {
+  const resultMap = new Map<string, ParameterObject>();
+
+  for (const [name, param] of pathParams.entries()) {
+    resultMap.set(name, param);
+  }
+
+  for (const [name, param] of schemaParams.entries()) {
+    resultMap.set(name, param);
+  }
+
+  return Array.from(resultMap.values());
+};
+
+const syncFunc: GetSyncFunction<GetPathParameterHelper> = ({
+  transformSchema,
+  appRoute,
+  id,
+  concatenatedPath,
+}) => {
+  const schema = appRoute.pathParams;
+
+  const paramsMap = getParamsFromPathOnly(appRoute.path);
+
+  const transformedSchema = transformSchema({
+    schema,
+    appRoute,
+    id,
+    concatenatedPath,
+    type: 'path',
+  });
+
+  if (!transformedSchema) {
+    return Array.from(paramsMap.values());
+  }
+
+  const schemaParams = schemaObjectToParameters(transformedSchema, 'path');
+
+  const schemaParamsMap = new Map(
+    schemaParams.map((param) => [param.name, param]),
+  );
+
+  return mergeParams(paramsMap, schemaParamsMap);
+};
+
+const asyncFunc: GetAsyncFunction<GetPathParameterHelper> = async ({
+  transformSchema,
+  appRoute,
+  id,
+  concatenatedPath,
+}) => {
+  const schema = appRoute.pathParams;
+
+  const paramsMap = getParamsFromPathOnly(appRoute.path);
+
+  const transformedSchema = await transformSchema({
+    schema,
+    appRoute,
+    id,
+    concatenatedPath,
+    type: 'path',
+  });
+
+  if (!transformedSchema) {
+    return Array.from(paramsMap.values());
+  }
+
+  const schemaParams = schemaObjectToParameters(transformedSchema, 'path');
+
+  const schemaParamsMap = new Map(
+    schemaParams.map((param) => [param.name, param]),
+  );
+
+  return mergeParams(paramsMap, schemaParamsMap);
+};
+
+export const getPathParameterSchema: GetPathParameterHelper = {
+  sync: syncFunc,
+  async: asyncFunc,
+};

package/src/lib/parsers/query-params.spec.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { getQueryParameterSchema } from './query-params';
+import { ZOD_SYNC, ZOD_ASYNC } from './test-helpers';
+
+describe('query-params', () => {
+  describe('zod', () => {
+    it('sync - single required param ', async () => {
+      const res = getQueryParameterSchema.sync({
+        transformSchema: ZOD_SYNC,
+        appRoute: {
+          method: 'GET',
+          path: '/',
+          query: z.object({
+            name: z.string(),
+          }),
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(res).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          required: true,
+          schema: {
+            type: 'string',
+          },
+        },
+      ]);
+    });
+
+    it('sync - single optional param', async () => {
+      const res = getQueryParameterSchema.sync({
+        transformSchema: ZOD_SYNC,
+        appRoute: {
+          method: 'GET',
+          path: '/',
+          query: z.object({
+            name: z.string().optional(),
+          }),
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(res).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          schema: {
+            type: 'string',
+          },
+        },
+      ]);
+    });
+
+    it('async - single required param ', async () => {
+      const res = await getQueryParameterSchema.async({
+        transformSchema: ZOD_ASYNC,
+        appRoute: {
+          method: 'GET',
+          path: '/',
+          query: z.object({
+            name: z.string(),
+          }),
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(res).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          required: true,
+          schema: {
+            type: 'string',
+          },
+        },
+      ]);
+    });
+
+    it('async - single optional param', async () => {
+      const result = await getQueryParameterSchema.async({
+        transformSchema: ZOD_ASYNC,
+        appRoute: {
+          method: 'GET',
+          path: '/',
+          query: z.object({
+            name: z.string().optional(),
+          }),
+          responses: {
+            200: z.object({
+              name: z.string(),
+            }),
+          },
+        },
+        id: 'testFunc',
+        concatenatedPath: 'testFunc',
+      });
+
+      expect(result).toEqual([
+        {
+          name: 'name',
+          in: 'query',
+          schema: {
+            type: 'string',
+          },
+        },
+      ]);
+    });
+  });
+});

package/src/lib/parsers/query-params.ts

@@ -0,0 +1,89 @@
+import { AppRoute, isStandardSchema } from '@sapporta/rest-core';
+import {
+  AsyncAndSyncHelper,
+  GetAsyncFunction,
+  GetSyncFunction,
+  SchemaTransformerAsync,
+  SchemaTransformerSync,
+} from '../types';
+import { ParameterObject } from 'openapi3-ts';
+import { schemaObjectToParameters } from './utils';
+
+type GetQueryParameterHelper = AsyncAndSyncHelper<
+  {
+    appRoute: AppRoute;
+    id: string;
+    concatenatedPath: string;
+    jsonQuery?: boolean;
+  },
+  {
+    transformSchema: SchemaTransformerSync;
+  },
+  {
+    transformSchema: SchemaTransformerAsync;
+  },
+  Array<ParameterObject>
+>;
+
+const syncFunc: GetSyncFunction<GetQueryParameterHelper> = ({
+  transformSchema,
+  appRoute,
+  id,
+  concatenatedPath,
+  jsonQuery = false,
+}) => {
+  const schema = appRoute.query;
+  const isSchema = isStandardSchema(schema);
+
+  if (!isSchema) {
+    return [];
+  }
+
+  const transformedSchema = transformSchema({
+    schema,
+    appRoute,
+    id,
+    concatenatedPath,
+    type: 'query',
+  });
+
+  if (!transformedSchema) {
+    return [];
+  }
+
+  return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
+};
+
+const asyncFunc: GetAsyncFunction<GetQueryParameterHelper> = async ({
+  transformSchema,
+  appRoute,
+  id,
+  concatenatedPath,
+  jsonQuery = false,
+}) => {
+  const schema = appRoute.query;
+  const isSchema = isStandardSchema(schema);
+
+  if (!isSchema) {
+    return [];
+  }
+
+  const transformedSchema = await transformSchema({
+    schema,
+    appRoute,
+    id,
+    concatenatedPath,
+    type: 'query',
+  });
+
+  if (!transformedSchema) {
+    return [];
+  }
+
+  return schemaObjectToParameters(transformedSchema, 'query', jsonQuery);
+};
+
+export const getQueryParameterSchema: GetQueryParameterHelper = {
+  sync: syncFunc,
+  async: asyncFunc,
+};

package/src/lib/parsers/test-helpers.ts

@@ -0,0 +1,26 @@
+import { SchemaObject } from 'openapi3-ts';
+import { z } from 'zod';
+import { SchemaTransformerAsync, SchemaTransformerSync } from '../types';
+
+const stripJsonSchemaMetadata = (schema: unknown): SchemaObject => {
+  if (!schema || typeof schema !== 'object') {
+    return schema as SchemaObject;
+  }
+
+  const { $schema, ...rest } = schema as Record<string, unknown>;
+  return rest as SchemaObject;
+};
+
+export const zodV4SchemaTransformer: SchemaTransformerSync = ({ schema }) => {
+  if (!schema || typeof schema !== 'object' || !('_zod' in schema)) {
+    return null;
+  }
+
+  return stripJsonSchemaMetadata(z.toJSONSchema(schema as z.ZodTypeAny));
+};
+
+export const ZOD_SYNC = zodV4SchemaTransformer;
+
+export const ZOD_ASYNC: SchemaTransformerAsync = async (args) => {
+  return zodV4SchemaTransformer(args);
+};