@pikku/cli 0.6.6

package/src/http/serialize-fetch-wrapper.ts

@@ -0,0 +1,57 @@
+export const serializeFetchWrapper = (routesMapPath: string) => {
+  return `
+import { CorePikkuFetch, HTTPMethod } from '@pikku/fetch'
+import type { RoutesMap, RouteHandlerOf, RoutesWithMethod } from '${routesMapPath}'
+
+export class PikkuFetch extends AbstractPikkuFetch {
+    public async post<Route extends RoutesWithMethod<'POST'>>(
+        route: Route,
+        data: RouteHandlerOf<Route, 'POST'>['input'] = null,
+        options?: Omit<RequestInit, 'body'>
+    ): Promise<RouteHandlerOf<Route, 'POST'>['output']> {
+        return super.api(route, 'POST', data, options);
+    }
+
+    public async get<Route extends RoutesWithMethod<'GET'>>(
+        route: Route,
+        data: RouteHandlerOf<Route, 'GET'>['input'] = null,
+        options?: Omit<RequestInit, 'body'>
+    ): Promise<RouteHandlerOf<Route, 'GET'>['output']> {
+        return super.api(route, 'GET', data, options);
+    }
+
+    public async patch<Route extends RoutesWithMethod<'PATCH'>>(
+        route: Route,
+        data: RouteHandlerOf<Route, 'PATCH'>['input'] = null,
+        options?: Omit<RequestInit, 'body'>
+    ): Promise<RouteHandlerOf<Route, 'PATCH'>['output']> {
+        return super.api(route, 'PATCH', data, options);
+    }
+
+    public async head<Route extends RoutesWithMethod<'HEAD'>>(
+        route: Route,
+        data: RouteHandlerOf<Route, 'HEAD'>['input'] = null,
+        options?: Omit<RequestInit, 'body'>
+    ): Promise<RouteHandlerOf<Route, 'HEAD'>['output']> {
+        return super.api(route, 'HEAD', data, options);
+    }
+
+    public async delete<Route extends RoutesWithMethod<'DELETE'>>(
+        route: Route,
+        data: RouteHandlerOf<Route, 'DELETE'>['input'] = null,
+        options?: Omit<RequestInit, 'body'>
+    ): Promise<RouteHandlerOf<Route, 'DELETE'>['output']> {
+        return super.api(route, 'DELETE', data, options);
+    }
+
+    public async fetch<
+        Route extends keyof RoutesMap,
+        Method extends keyof RoutesMap[Route]
+    >(route: Route, method: Method, data: RouteHandlerOf<Route, Method>['input'], options?: Omit<RequestInit, 'body'>): Promise<Response> {
+        return await super.fetch(route, method as HTTPMethod, data, options)
+    }
+}
+
+export const pikkuFetch = new PikkuFetch()
+`
+}

package/src/http/serialize-route-imports.ts

@@ -0,0 +1,24 @@
+import { getFileImportRelativePath } from '../utils.js'
+
+export const serializeRoutes = (
+  outputPath: string,
+  filesWithRoutes: Set<string>,
+  packageMappings: Record<string, string> = {}
+) => {
+  const serializedOutput: string[] = [
+    '/* The files with an addRoute function call */',
+  ]
+
+  Array.from(filesWithRoutes)
+    .sort()
+    .forEach((path) => {
+      const filePath = getFileImportRelativePath(
+        outputPath,
+        path,
+        packageMappings
+      )
+      serializedOutput.push(`import '${filePath}'`)
+    })
+
+  return serializedOutput.join('\n')
+}

package/src/http/serialize-route-meta.ts

@@ -0,0 +1,10 @@
+import type { HTTPRoutesMeta } from '@pikku/core/http'
+
+export const serializeHTTPRoutesMeta = (routesMeta: HTTPRoutesMeta) => {
+  const serializedOutput: string[] = []
+  serializedOutput.push("import { setHTTPRoutesMeta } from '@pikku/core/http'")
+  serializedOutput.push(
+    `setHTTPRoutesMeta(${JSON.stringify(routesMeta, null, 2)})`
+  )
+  return serializedOutput.join('\n')
+}

package/src/http/serialize-typed-route-map.ts

@@ -0,0 +1,147 @@
+import { HTTPRoutesMeta } from '@pikku/core/http'
+import { serializeImportMap } from '../core/serialize-import-map.js'
+import { MetaInputTypes, TypesMap } from '@pikku/inspector'
+
+export const serializeTypedRoutesMap = (
+  relativeToPath: string,
+  packageMappings: Record<string, string>,
+  typesMap: TypesMap,
+  routesMeta: HTTPRoutesMeta,
+  metaTypes: MetaInputTypes
+) => {
+  const requiredTypes = new Set<string>()
+  const serializedCustomTypes = generateCustomTypes(typesMap, requiredTypes)
+  const serializedMetaTypes = generateMetaTypes(metaTypes, typesMap)
+  const serializedImportMap = serializeImportMap(
+    relativeToPath,
+    packageMappings,
+    typesMap,
+    requiredTypes
+  )
+  const serializedRoutes = generateRoutes(routesMeta, typesMap, requiredTypes)
+
+  return `/**
+ * This provides the structure needed for typescript to be aware of routes and their return types
+ */
+    
+${serializedImportMap}
+${serializedCustomTypes}
+${serializedMetaTypes}
+
+interface RouteHandler<I, O> {
+    input: I;
+    output: O;
+}
+
+${serializedRoutes}
+
+export type RouteHandlerOf<Route extends keyof RoutesMap, Method extends keyof RoutesMap[Route]> =
+    RoutesMap[Route][Method] extends { input: infer I; output: infer O }
+        ? RouteHandler<I, O>
+        : never;
+
+export type RoutesWithMethod<Method extends string> = {
+  [Route in keyof RoutesMap]: Method extends keyof RoutesMap[Route] ? Route : never;
+}[keyof RoutesMap];
+  `
+}
+
+function generateCustomTypes(typesMap: TypesMap, requiredTypes: Set<string>) {
+  return `
+// Custom types are those that are defined directly within generics
+// or are broken into simpler types
+${Array.from(typesMap.customTypes.entries())
+  .map(([name, { type, references }]) => {
+    references.forEach((name) => {
+      const originalName = typesMap.getTypeMeta(name).originalName
+      requiredTypes.add(originalName)
+    })
+    return `export type ${name} = ${type}`
+  })
+  .join('\n')}`
+}
+
+function generateRoutes(
+  routesMeta: HTTPRoutesMeta,
+  typesMap: TypesMap,
+  requiredTypes: Set<string>
+) {
+  // Initialize an object to collect routes
+  const routesObj: Record<
+    string,
+    Record<string, { inputType: string; outputType: string }>
+  > = {}
+
+  for (const meta of routesMeta) {
+    const { route, method, input, output } = meta
+
+    // Initialize the route entry if it doesn't exist
+    if (!routesObj[route]) {
+      routesObj[route] = {}
+    }
+
+    // Store the input and output types separately for RouteHandler
+    const inputType = input ? typesMap.getTypeMeta(input).uniqueName : 'null'
+    const outputType = output ? typesMap.getTypeMeta(output).uniqueName : 'null'
+
+    requiredTypes.add(inputType)
+    requiredTypes.add(outputType)
+
+    // Add method entry
+    routesObj[route][method] = {
+      inputType,
+      outputType,
+    }
+  }
+
+  // Build the routes object as a string
+  let routesStr = 'export type RoutesMap = {\n'
+
+  for (const [routePath, methods] of Object.entries(routesObj)) {
+    routesStr += `  readonly '${routePath}': {\n`
+    for (const [method, handler] of Object.entries(methods)) {
+      routesStr += `    readonly ${method.toUpperCase()}: RouteHandler<${handler.inputType}, ${handler.outputType}>,\n`
+    }
+    routesStr += '  },\n'
+  }
+
+  routesStr += '};'
+
+  return routesStr
+}
+
+const generateMetaTypes = (metaTypes: MetaInputTypes, typesMap: TypesMap) => {
+  const nameToTypeMap = Array.from(metaTypes.entries()).reduce<
+    Map<string, string>
+  >((result, [_name, { query, body, params }]) => {
+    const { uniqueName } = typesMap.getTypeMeta(_name)
+    const queryType =
+      query && query.length > 0
+        ? `Pick<${uniqueName}, '${query?.join("' | '")}'>`
+        : undefined
+    if (queryType) {
+      result.set(`${uniqueName}Query`, queryType)
+    }
+    const paramsType =
+      params && params.length > 0
+        ? `Pick<${uniqueName}, '${params.join("' | '")}'>`
+        : undefined
+    if (paramsType) {
+      result.set(`${uniqueName}Params`, paramsType)
+    }
+    const bodyType =
+      (body && body.length > 0) || (params && params.length > 0)
+        ? `Omit<${uniqueName}, '${[...new Set([...(query || []), ...(params || [])])].join("' | '")}'>`
+        : uniqueName!
+    if (bodyType) {
+      result.set(`${uniqueName}Body`, bodyType)
+    }
+    return result
+  }, new Map())
+
+  return `
+// The '& {}' is a workaround for not directly refering to a type since it confuses typescript
+${Array.from(nameToTypeMap.entries())
+  .map(([name, type]) => `export type ${name} = ${type} & {}`)
+  .join('\n')}`
+}

package/src/inspector-glob.ts

@@ -0,0 +1,27 @@
+import * as path from 'path'
+import { glob } from 'glob'
+import { InspectorState, inspect } from '@pikku/inspector'
+import { logCommandInfoAndTime } from './utils.js'
+
+export const inspectorGlob = async (
+  rootDir: string,
+  routeDirectories: string[]
+) => {
+  let result: InspectorState
+  await logCommandInfoAndTime(
+    'Inspecting codebase',
+    'Inspected codebase',
+    [false],
+    async () => {
+      const routeFiles = (
+        await Promise.all(
+          routeDirectories.map((dir) =>
+            glob(`${path.join(rootDir, dir)}/**/*.ts`)
+          )
+        )
+      ).flat()
+      result = await inspect(routeFiles)
+    }
+  )
+  return result!
+}

package/src/nextjs/serialize-nextjs-wrapper.ts

@@ -0,0 +1,156 @@
+export const serializeNextJsWrapper = (
+  routesPath: string,
+  routesMapPath: string,
+  schemasPath: string,
+  configImport: string,
+  singleServicesFactoryImport: string,
+  sessionServicesImport: string
+) => {
+  return `'server-only'
+
+/**
+ * This file provides a wrapper around the PikkuNextJS class to allow for methods to be type checked against your routes.
+ * This ensures type safety for route handling methods when integrating with the \`@pikku/core\` framework.
+ */
+import { PikkuNextJS } from '@pikku/next'
+import type { RoutesMap, RouteHandlerOf, RoutesWithMethod } from '${routesMapPath}'
+
+${configImport}
+${singleServicesFactoryImport}
+${sessionServicesImport}
+
+import '${routesPath}'
+import '${schemasPath}'
+
+let _pikku: PikkuNextJS | undefined
+
+/**
+ * Initializes and returns an instance of PikkuNextJS with helper methods for handling route requests.
+ *
+ * @returns An object containing methods for making dynamic and static action requests.
+ */
+export const pikku = () => {
+  if (!_pikku) {
+    _pikku = new PikkuNextJS(
+      createConfig as any,
+      createSingletonServices as any,
+      createSessionServices
+    )
+  }
+
+  /**
+   * Makes a dynamic action request for a specified route and method.
+   * Dynamic requests may access headers and cookies, making them unsuitable for precompile stages.
+   *
+   * @template Route - The route key from the RoutesMap.
+   * @template Method - The method key from the specified route.
+   * @param route - The route to make the request to.
+   * @param method - The method to be used for the request.
+   * @param data - The input data for the request, defaults to null.
+   * @returns A promise that resolves to the output of the route handler.
+   */
+  const dynamicActionRequest = async <
+    Route extends keyof RoutesMap,
+    Method extends keyof RoutesMap[Route]
+  >(
+    route: Route,
+    method: Method,
+    data: RouteHandlerOf<Route, Method>['input'] = null
+  ): Promise<RouteHandlerOf<Route, Method>['output']> => {
+    return _pikku!.actionRequest(route, method, data as any)
+  }
+
+  /**
+   * Makes a static action request for a specified route and method.
+   * Static requests do not depend on headers or cookies and are suitable for precompile stages.
+   *
+   * @template Route - The route key from the RoutesMap.
+   * @template Method - The method key from the specified route.
+   * @param route - The route to make the request to.
+   * @param method - The method to be used for the request.
+   * @param data - The input data for the request, defaults to null.
+   * @returns A promise that resolves to the output of the route handler.
+   */
+  const staticActionRequest = async <
+    Route extends keyof RoutesMap,
+    Method extends keyof RoutesMap[Route]
+  >(
+    route: Route,
+    method: Method,
+    data: RouteHandlerOf<Route, Method>['input'] = null
+  ): Promise<RouteHandlerOf<Route, Method>['output']> => {
+    return _pikku!.staticActionRequest(route, method, data as any)
+  }
+
+  /**
+   * Makes a dynamic POST request for a specified route.
+   */
+  const dynamicPost = <Route extends RoutesWithMethod<'POST'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'POST'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'POST'>['output']> => {
+    return dynamicActionRequest(route, 'POST', data)
+  }
+
+  /**
+   * Makes a dynamic GET request for a specified route.
+   */
+  const dynamicGet = <Route extends RoutesWithMethod<'GET'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'GET'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'GET'>['output']> => {
+    return dynamicActionRequest(route, 'GET', data)
+  }
+
+  /**
+   * Makes a dynamic PATCH request for a specified route.
+   */
+  const dynamicPatch = <Route extends RoutesWithMethod<'PATCH'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'PATCH'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'PATCH'>['output']> => {
+    return dynamicActionRequest(route, 'PATCH', data)
+  }
+
+  /**
+   * Makes a dynamic DELETE request for a specified route.
+   */
+  const dynamicDel = <Route extends RoutesWithMethod<'DELETE'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'DELETE'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'DELETE'>['output']> => {
+    return dynamicActionRequest(route, 'DELETE', data)
+  }
+
+  // Static
+
+  /**
+   * Makes a static POST request for a specified route.
+   */
+  const staticPost = <Route extends RoutesWithMethod<'POST'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'POST'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'POST'>['output']> => {
+    return staticActionRequest(route, 'POST', data)
+  }
+
+  /**
+   * Makes a static GET request for a specified route.
+   */
+  const staticGet = <Route extends RoutesWithMethod<'GET'>>(
+    route: Route,
+    data: RouteHandlerOf<Route, 'GET'>['input'] = null
+  ): Promise<RouteHandlerOf<Route, 'GET'>['output']> => {
+    return staticActionRequest(route, 'GET', data)
+  }
+
+  return {
+    get: dynamicGet,
+    post: dynamicPost,
+    patch: dynamicPatch,
+    del: dynamicDel,
+    staticGet,
+    staticPost
+  }
+}`
+}

package/src/openapi/openapi-spec-generator.ts

@@ -0,0 +1,229 @@
+import { getErrors } from '@pikku/core/errors'
+import { HTTPRoutesMeta } from '@pikku/core/http'
+import _convertSchema from '@openapi-contrib/json-schema-to-openapi-schema'
+const convertSchema =
+  'default' in _convertSchema ? (_convertSchema.default as any) : _convertSchema
+
+interface OpenAPISpec {
+  openapi: string
+  info: {
+    title: string
+    version: string
+    description?: string
+    termsOfService?: string
+    contact?: {
+      name?: string
+      url?: string
+      email?: string
+    }
+    license?: {
+      name: string
+      url?: string
+    }
+  }
+  servers: { url: string; description?: string }[]
+  paths: Record<string, any>
+  components: {
+    schemas: Record<string, any>
+    responses?: Record<string, any>
+    parameters?: Record<string, any>
+    examples?: Record<string, any>
+    requestBodies?: Record<string, any>
+    headers?: Record<string, any>
+    securitySchemes?: Record<string, any>
+  }
+  security?: { [key: string]: any[] }[]
+  tags?: { name: string; description?: string }[]
+  externalDocs?: {
+    description?: string
+    url: string
+  }
+}
+
+export interface OpenAPISpecInfo {
+  info: {
+    title: string
+    version: string
+    description: string
+    termsOfService?: string
+    contact?: {
+      name?: string
+      url?: string
+      email?: string
+    }
+    license?: {
+      name: string
+      url?: string
+    }
+  }
+  servers: { url: string; description?: string }[]
+  tags?: { name: string; description?: string }[]
+  externalDocs?: {
+    description?: string
+    url: string
+  }
+  securitySchemes?: Record<string, any>
+  security?: { [key: string]: any[] }[]
+}
+
+const getErrorResponseForConstructorName = (constructorName: string) => {
+  const foundError = Array.from(getErrors().entries()).find(
+    ([e]) => e.name === constructorName
+  )
+  if (foundError) {
+    return foundError[1]
+  }
+  return undefined
+}
+
+const convertSchemasToBodyPayloads = async (
+  routesMeta: HTTPRoutesMeta,
+  schemas: Record<string, any>
+) => {
+  const requiredSchemas = new Set(
+    routesMeta
+      .map(({ inputTypes, output }) => [inputTypes?.body, output])
+      .flat()
+      .filter((schema) => !!schema)
+  )
+  const convertedEntries = await Promise.all(
+    Object.entries(schemas).map(async ([key, schema]) => {
+      if (requiredSchemas.has(key)) {
+        const convertedSchema = await convertSchema(schema, {
+          convertUnreferencedDefinitions: false,
+          dereference: { circular: 'ignore' },
+        })
+        return [key, convertedSchema]
+      }
+      return
+    })
+  )
+  return Object.fromEntries(convertedEntries.filter((s) => !!s))
+}
+
+export async function generateOpenAPISpec(
+  routeMeta: HTTPRoutesMeta,
+  schemas: Record<string, any>,
+  additionalInfo: OpenAPISpecInfo
+): Promise<OpenAPISpec> {
+  const paths: Record<string, any> = {}
+
+  routeMeta.forEach((meta) => {
+    const { route, method, inputTypes, output, params, query, docs } = meta
+    const path = route.replace(/:(\w+)/g, '{$1}') // Convert ":param" to "{param}"
+
+    if (!paths[path]) {
+      paths[path] = {}
+    }
+
+    const responses = {}
+    docs?.errors?.forEach((error) => {
+      const errorResponse = getErrorResponseForConstructorName(error)
+      if (errorResponse) {
+        responses[errorResponse.status] = {
+          description: errorResponse.message,
+        }
+      }
+    })
+
+    const operation: any = {
+      description:
+        docs?.description ||
+        `This endpoint handles the ${method.toUpperCase()} request for the route ${route}.`,
+      tags: docs?.tags || [route.split('/')[1] || 'default'],
+      parameters: [],
+      responses: {
+        ...responses,
+        '200': {
+          description: 'Successful response',
+          content: output
+            ? {
+                'application/json': {
+                  schema:
+                    typeof output === 'string' &&
+                    ['boolean', 'string', 'number'].includes(output)
+                      ? { type: output }
+                      : { $ref: `#/components/schemas/${output}` },
+                },
+              }
+            : undefined,
+        },
+      },
+    }
+
+    const bodyType = inputTypes?.body
+    if (bodyType) {
+      operation.requestBody = {
+        required: true,
+        content: {
+          'application/json': {
+            schema:
+              typeof bodyType === 'string' &&
+              ['boolean', 'string', 'number'].includes(bodyType)
+                ? { type: bodyType }
+                : { $ref: `#/components/schemas/${bodyType}` },
+          },
+        },
+      }
+    }
+
+    if (params) {
+      operation.parameters = params.map((param) => ({
+        name: param,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      }))
+    }
+
+    if (query) {
+      operation.parameters.push(
+        ...query.map((query) => ({
+          name: query,
+          in: 'query',
+          required: false,
+          schema: { type: 'string' },
+        }))
+      )
+    }
+
+    paths[path][method] = operation
+  })
+
+  return {
+    openapi: '3.1.0',
+    info: additionalInfo.info,
+    servers: additionalInfo.servers,
+    paths,
+    components: {
+      schemas: await convertSchemasToBodyPayloads(routeMeta, schemas),
+      responses: {},
+      parameters: {},
+      examples: {},
+      requestBodies: {},
+      headers: {},
+      securitySchemes: additionalInfo.securitySchemes || {
+        ApiKeyAuth: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'x-api-key',
+        },
+        BearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+        },
+      },
+    },
+    security: additionalInfo.security || [
+      {
+        ApiKeyAuth: [],
+      },
+      {
+        BearerAuth: [],
+      },
+    ],
+    tags: additionalInfo.tags,
+    externalDocs: additionalInfo.externalDocs,
+    // definitions
+  }
+}