Merge pull request #2 from jackdbd/canary

Merge `canary` into `main`

.ae/zod-to-doc.api.md

@@ -36,7 +36,7 @@ export const markdownTableFromZodSchema: <S extends z.AnyZodObject>(schema: S) =
 // Warning: (ae-internal-missing-underscore) The name "stringify" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal (undocumented)
-export const stringify: (x: any) => any;
+export const stringify: (x: any) => string;
 
 // (No @packageDocumentation comment for this package)
 

.github/workflows/ci.yaml

@@ -101,7 +101,7 @@ jobs:
       fail-fast: true
       matrix:
         os: [macos-latest]
-        node: [ lts/Iron]
+        node: [lts/Iron]
     steps:
       - name: 🛎️ Checkout repo
         uses: actions/checkout@v4
@@ -127,7 +127,7 @@ jobs:
       fail-fast: true
       matrix:
         os: [windows-latest]
-        node: [ lts/Iron]
+        node: [lts/Iron]
     steps:
       - name: 🛎️ Checkout repo
         uses: actions/checkout@v4

CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## [1.0.4-canary.2](https://github.com/jackdbd/zod-to-doc/compare/v1.0.4-canary.1...v1.0.4-canary.2) (2024-02-06)
+
+
+### Bug Fixes
+
+* modify package entry points ([09c700a](https://github.com/jackdbd/zod-to-doc/commit/09c700abc9991d6fe28040f4c18d3004d63f168d))
+
+## [1.0.4-canary.1](https://github.com/jackdbd/zod-to-doc/compare/v1.0.3...v1.0.4-canary.1) (2024-02-06)
+
+
+### Bug Fixes
+
+* modify package entry points ([6aad7d1](https://github.com/jackdbd/zod-to-doc/commit/6aad7d13e8ee7459ee8b3285a7414e0ebbe12622))
+
 ## [1.0.3](https://github.com/jackdbd/zod-to-doc/compare/v1.0.2...v1.0.3) (2024-02-02)
 
 

README.md

@@ -10,17 +10,23 @@
 
 Inject your [Zod](https://github.com/colinhacks/zod) schemas into your docs.
 
+- [About](#about)
 - [Installation](#installation)
 - [Docs](#docs)
 - [Examples](#examples)
   - [Usage as a CLI](#usage-as-a-cli)
     - [Car table](#car-table)
   - [Usage as a library](#usage-as-a-library)
     - [Car tire table](#car-tire-table)
+    - [Dealership](#dealership)
 - [Troubleshooting](#troubleshooting)
 - [Dependencies](#dependencies)
 - [License](#license)
 
+## About
+
+I was looking for a way to keep my documentation updated with my Zod schemas. To my surprise, I couldn't find any tool that would output a string representation of a Zod schema. So I decided to write my own. You can use this tool either as a library or as a CLI.
+
 ## Installation
 
 ```sh
@@ -31,7 +37,7 @@ npm install --save-dev @jackdbd/zod-to-doc
 
 [Docs generated by TypeDoc](https://jackdbd.github.io/zod-to-doc/index.html)
 
-> :open_book: **API Docs**
+> 📖 **API Docs**
 >
 > This project uses [API Extractor](https://api-extractor.com/) and [api-documenter markdown](https://api-extractor.com/pages/commands/api-documenter_markdown/) to generate a bunch of markdown files and a `.d.ts` rollup file containing all type definitions consolidated into a single file. I don't find this `.d.ts` rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.
 >
@@ -80,6 +86,15 @@ Zod to Doc can also be used as a library. For example, the [readme.ts](https://g
 | `manufacturer` | `undefined` | Car tire manufacturer |
 | `pressure` | `30` | Car tire pressure in PSI |
 
+#### Dealership
+
+| Key | Default | Description |
+|---|---|---|
+| `owner` | `undefined` | Owner of the dealership |
+| `employees` | `undefined` | Employees of the dealership (1 to ∞ elements) |
+| `cars` | `[]` | Cars sold by the dealership |
+| `motorcycles` | `[]` | Motorcycles sold by the dealership |
+
 ## Troubleshooting
 
 This package uses the [debug](https://github.com/debug-js/debug) library for logging.
@@ -96,6 +111,7 @@ export DEBUG=ztd:*
 
 | Package | Version |
 |---|---|
+| [debug](https://www.npmjs.com/package/debug) | `^4.3.4` |
 | [zod](https://www.npmjs.com/package/zod) | `^3.22.4` |
 
 ## License

fixtures/schemas.mjs

@@ -4,13 +4,31 @@ export const car_manufacturer = z
   .literal('Ferrari')
   .or(z.literal('Ford'))
   .or(z.literal('Ford'))
+  .or(z.literal('Honda'))
   .or(z.literal('Peugeot'))
   .or(z.literal('Toyota'))
   .or(z.literal('Volkswagen'))
   .describe('Car manufacturer')
 
+export const motorcycle_manufacturer = z
+  .literal('Aprilia')
+  .or(z.literal('BMW'))
+  .or(z.literal('Ducati'))
+  .or(z.literal('Harley Davidson'))
+  .or(z.literal('Honda'))
+  .or(z.literal('Kawasaki'))
+  .or(z.literal('KTM'))
+  .or(z.literal('Royal Enfield'))
+  .or(z.literal('Suzuki'))
+  .or(z.literal('SWM'))
+  .or(z.literal('Triumph'))
+  .or(z.literal('Yamaha'))
+  .describe('Motorcycle manufacturer')
+
 export const car_model = z.string().min(1).describe('Car model')
 
+export const motorcycle_model = z.string().min(1).describe('Motorcycle model')
+
 export const year = z.number().min(1900).max(2024)
 
 export const car_tire_pressure = z
@@ -19,6 +37,12 @@ export const car_tire_pressure = z
   .max(42)
   .describe('Car tire pressure in PSI')
 
+export const motorcycle_tire_pressure = z
+  .number()
+  .min(28)
+  .max(42)
+  .describe('Motorcycle tire pressure in PSI')
+
 export const car_tire_manufacturer = z
   .literal('Bridgestone')
   .or(z.literal('Continental'))
@@ -28,14 +52,64 @@ export const car_tire_manufacturer = z
   .or(z.literal('Yokohama'))
   .describe('Car tire manufacturer')
 
+export const motorcycle_tire_manufacturer = z
+  .literal('Bridgestone')
+  .or(z.literal('Continental'))
+  .or(z.literal('Goodyear'))
+  .or(z.literal('Michelin'))
+  .or(z.literal('Pirelli'))
+  .or(z.literal('Yokohama'))
+  .describe('Motorcycle tire manufacturer')
+
 export const car_tire = z.object({
   manufacturer: car_tire_manufacturer,
   pressure: car_tire_pressure.default(30)
 })
 
+export const motorcycle_tire = z.object({
+  manufacturer: motorcycle_tire_manufacturer,
+  pressure: motorcycle_tire_pressure.default(32)
+})
+
 export const car = z.object({
   manufacturer: car_manufacturer,
   model: car_model,
   tires: z.array(car_tire).length(4),
   year: year.describe('Year in which the car was manufactured')
 })
+
+export const motorcycle = z.object({
+  manufacturer: motorcycle_manufacturer,
+  model: motorcycle_model,
+  tires: z.array(motorcycle_tire).length(2),
+  year: year.describe('Year in which the motorcycle was manufactured')
+})
+
+export const person_name = z.string().min(1).describe('Name of the person')
+
+export const job_title = z.string().min(1).describe('Job title')
+
+export const JOBS = ['mechanic', 'salesman']
+
+export const employee = z
+  .object({
+    job_title: job_title.refine((title) => JOBS.includes(title), {
+      message: `job_title must be one of: ${JOBS.join(' ')}`
+    }),
+    name: person_name.describe('Name of the employee')
+  })
+  .describe('Employee')
+
+export const business_owner = z.object({
+  name: person_name.describe('Name of the business owner')
+})
+
+export const dealership = z.object({
+  owner: business_owner.describe('Owner of the dealership'),
+  employees: z.array(employee).min(1).describe('Employees of the dealership'),
+  cars: z.array(car).default([]).describe('Cars sold by the dealership'),
+  motorcycles: z
+    .array(motorcycle)
+    .default([])
+    .describe('Motorcycles sold by the dealership')
+})

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackdbd/zod-to-doc",
-  "version": "1.0.3",
+  "version": "1.0.4-canary.2",
   "description": "Inject your [Zod](https://github.com/colinhacks/zod) schemas into your docs.",
   "author": {
     "name": "Giacomo Debidda",
@@ -29,16 +29,20 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/cli.js"
+      "import": "./dist/lib.js",
+      "types": "./dist/lib.d.ts"
     },
     "./lib": {
-      "types": "./dist/lib.d.ts",
-      "import": "./dist/lib.js"
+      "import": "./dist/lib.js",
+      "types": "./dist/lib.d.ts"
     },
     "./package.json": "./package.json"
   },
   "typesVersions": {
     ">=4.0": {
+      "index": [
+        "./dist/lib.d.ts"
+      ],
       "*": [
         "./dist/*.d.ts"
       ]
@@ -71,12 +75,13 @@
     "nuke": "npm run clean && rimraf node_modules 'package-lock.json'",
     "readme": "npm run example && tsm readme.ts",
     "release:dry": "semantic-release --debug --dry-run --no-ci",
-    "size": "pkg-size ./dist --sort-by=brotli --ignore-files {*.d.ts,*.map}",
-    "test": "node --test --experimental-test-coverage",
+    "size": "pkg-size ./dist --sort-by=brotli --ignore-files '{*.d.ts,*.map}'",
+    "test": "node --test --experimental-test-coverage --test-name-pattern=cli",
     "test:ci": "node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info",
     "test:watch": "node --test --watch"
   },
   "dependencies": {
+    "debug": "^4.3.4",
     "zod": "^3.22.4"
   },
   "devDependencies": {
@@ -90,7 +95,6 @@
     "@types/debug": "^4.1.12",
     "@types/yargs": "^17.0.32",
     "@typescript-eslint/eslint-plugin": "^6.19.1",
-    "debug": "^4.3.4",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",

readme.ts

@@ -12,8 +12,9 @@ import {
 } from '@thi.ng/transclude'
 import defDebug from 'debug'
 import { DEBUG_PREFIX } from './src/constants.js'
+// import { markdownTableFromZodSchema } from '@jackdbd/zod-to-doc'
 import { markdownTableFromZodSchema } from './src/lib.js'
-import { car, car_tire } from './fixtures/schemas.mjs'
+import { car, car_tire, dealership } from './fixtures/schemas.mjs'
 
 const debug = defDebug(`${DEBUG_PREFIX}:readme`)
 
@@ -36,7 +37,7 @@ const zodToTable = (schema: z.AnyZodObject) => {
   const { error, value } = markdownTableFromZodSchema(schema)
   if (error) {
     return callout({
-      emoji: ':warning:',
+      emoji: '❌', // or ⚠️
       title: `Could not generate table from Zod schema: ${error.name}`,
       message: error.message
     })
@@ -168,7 +169,7 @@ const main = async ({
           `[Docs generated by TypeDoc](https://${github_username}.github.io/${unscoped_pkg_name}/index.html)`,
           '\n\n',
           callout({
-            emoji: ':open_book:', // open_book, page_facing_up, page_with_curl
+            emoji: '📖', // open_book, page_facing_up, page_with_curl
             title: 'API Docs',
             message: `This project uses [API Extractor](https://api-extractor.com/) and [api-documenter markdown](https://api-extractor.com/pages/commands/api-documenter_markdown/) to generate a bunch of markdown files and a \`.d.ts\` rollup file containing all type definitions consolidated into a single file. I don't find this \`.d.ts\` rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.\n\n*See [Generating API docs](https://api-extractor.com/pages/setup/generating_docs/) if you want to know more*.`
           })
@@ -204,6 +205,7 @@ const main = async ({
       },
 
       'table.car': zodToTable(car),
+      'table.dealership': zodToTable(dealership),
       'table.tire': zodToTable(car_tire),
 
       troubleshooting: () => {

src/cli.ts

@@ -11,7 +11,7 @@ const debug = defDebug(`${DEBUG_PREFIX}:cli`)
 
 const argv = await yargs(process.argv.slice(2))
   .usage(
-    './$0 - Generated a markdown table from a Zod schema and write it to a file'
+    './$0 - Generate a markdown table from a Zod schema and write it to a file'
   )
   .option('module', {
     alias: 'm',