@specbook/codegen 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/codegen",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Turns an OpenAPI or Swagger document into types, examples, schemas and metadata, in Node or in a browser.",
   "keywords": [
     "specbook",
@@ -40,7 +40,7 @@
     "swagger2openapi": "7.0.8"
   },
   "devDependencies": {
-    "@specbook/core": "0.1.0",
+    "@specbook/core": "0.3.0",
     "@types/node": "24.19.2",
     "@types/swagger2openapi": "7.0.4",
     "typescript": "7.0.2"

package/src/build.ts

@@ -547,7 +547,7 @@ export function generateFromDoc(
           content: `import { defineOperation } from '${core}'
 import type * as T from '../types'
 
-${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))].join('\n\n'), deprecated: op.deprecated })}export const ${id} = defineOperation<{
+${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))].join('\n\n'), deprecated: op.deprecated })}export const ${id} = /* @__PURE__ */ defineOperation<{
   params: { ${paramsT} }
   body: ${bodyT}
   responses: { ${responseTypes.join('; ')} }
@@ -596,6 +596,8 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
       content: `${exportsFor(ids).replace(/'\.\/operations/g, "'../operations")}\n`,
     })
   }
+  // what a run needs of each operation (method, path, encoding…): the committed operations file is built from it
+  if (ts) files.push({ path: 'opmeta.json', content: `${JSON.stringify(metas, null, 2)}\n` })
   files.push({
     path: 'manifest.json',
     content: `${JSON.stringify(

package/src/generate.ts

@@ -1,3 +1,7 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
 import SwaggerParser from '@apidevtools/swagger-parser'
 import swagger2openapi from 'swagger2openapi'
 import {
@@ -5,12 +9,29 @@ import {
   type GenerateOptions,
   generateFromDoc,
   type ManifestOperation,
+  type OperationMeta,
 } from './build'
 
 export * from './build'
 
+/** Runs `use` with a spec the parser can read: a `.gz` one is unpacked to a temporary file of the same kind. */
+export async function withPlainSpec<T>(
+  spec: string | object,
+  use: (spec: string | object) => Promise<T>,
+): Promise<T> {
+  if (typeof spec !== 'string' || !spec.endsWith('.gz')) return use(spec)
+  const dir = await mkdtemp(join(tmpdir(), 'specbook-spec-'))
+  try {
+    const file = join(dir, basename(spec).replace(/\.gz$/, ''))
+    await writeFile(file, gunzipSync(await readFile(spec)))
+    return await use(file)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
 async function loadOpenApi3(spec: string | object): Promise<any> {
-  const bundled: any = await SwaggerParser.bundle(spec as any)
+  const bundled: any = await withPlainSpec(spec, (plain) => SwaggerParser.bundle(plain as any))
   if (bundled.swagger?.startsWith('2')) {
     const res = await swagger2openapi.convertObj(bundled, { patch: true, warnOnly: true } as any)
     return res.openapi
@@ -21,7 +42,9 @@ async function loadOpenApi3(spec: string | object): Promise<any> {
 export async function generate(opts: GenerateOptions): Promise<{
   files: GeneratedFile[]
   operations: ManifestOperation[]
+  /** what a request needs of each operation at run time, by operation id */
+  metas: Record<string, OperationMeta>
 }> {
-  const { files, operations } = generateFromDoc(await loadOpenApi3(opts.spec), opts)
-  return { files, operations }
+  const { files, operations, metas } = generateFromDoc(await loadOpenApi3(opts.spec), opts)
+  return { files, operations, metas }
 }

package/src/index.ts

@@ -5,6 +5,6 @@ export type {
   ManifestOperation,
   OperationMeta,
 } from './build'
-export { generate, generateFromDoc } from './generate'
+export { generate, generateFromDoc, withPlainSpec } from './generate'
 export { synthesize, tsType } from './schema'
-export { generateToDisk } from './write'
+export { generateToDisk, writeAtomically } from './write'

package/src/write.ts

@@ -17,7 +17,7 @@ let counter = 0
  * over the target (atomic on one file system). A file that already holds this content is left alone,
  * which keeps its timestamp and spares a watching dev server a reload for nothing.
  */
-async function writeAtomically(full: string, content: string): Promise<void> {
+export async function writeAtomically(full: string, content: string): Promise<void> {
   const current = await readFile(full, 'utf8').catch(() => undefined)
   if (current === content) return
   const tmp = `${full}.${process.pid}.${counter++}.tmp`