standard-schema + str presets (#36)

Author: mmkal

src/presets/index.ts

@@ -55,4 +55,6 @@ export * from './markdown-from-jsdoc'
 export * from './markdown-from-tests'
 export * from './markdown-toc'
 export * from './monorepo-toc'
+export * from './standard-schema'
+export * from './str'
 // codegen:end

src/presets/standard-schema.ts

@@ -0,0 +1,45 @@
+import {z} from 'zod/v4'
+import {definePreset} from './util/standard-schema-preset'
+
+/**
+ * Generates standard-schema boilerplate code. By default, includes:
+ *
+ * - the contract as defined in github.com/standard-schema/standard-schema.
+ * - some utils for checking if arbitrary values look like standard-schema schemas and errors.
+ * - a function for prettifying standard-schema errors.
+ * - a custom error class for standard-schema errors.
+ *
+ * All parts are optional - and of course you can use this generator to create the boilerplate once, then remove the codegen directives to modify manually
+ */
+export const standardSchema = definePreset(
+  z.object({
+    include: z.enum(['contract', 'errors', 'utils']).array().default(['contract', 'errors', 'utils']),
+  }),
+  ({options, meta, dependencies}) => {
+    const src = options.include
+      .map(include => {
+        if (include === 'contract') return standardSchemaV1ContractSrc
+        if (include === 'utils') return standardSchemaV1UtilsSrc
+        if (include === 'errors') return standardSchemaV1ErrorsSrc
+      })
+      .join('\n')
+
+    if (dependencies.simplify.equivalentSimplified(src, meta.existingContent)) return meta.existingContent || ''
+    return src
+  },
+)
+
+// codegen:start {preset: str, source: ../standard-schema/contract.ts, const: standardSchemaV1ContractSrc}
+const standardSchemaV1ContractSrc =
+  "// from https://github.com/standard-schema/standard-schema\n\n/** The Standard Schema interface. */\nexport interface StandardSchemaV1<Input = unknown, Output = Input> {\n  /** The Standard Schema properties. */\n  readonly '~standard': StandardSchemaV1.Props<Input, Output>\n}\n\nexport declare namespace StandardSchemaV1 {\n  /** The Standard Schema properties interface. */\n  export interface Props<Input = unknown, Output = Input> {\n    /** The version number of the standard. */\n    readonly version: 1\n    /** The vendor name of the schema library. */\n    readonly vendor: string\n    /** Validates unknown input values. */\n    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>\n    /** Inferred types associated with the schema. */\n    readonly types?: Types<Input, Output> | undefined\n  }\n\n  /** The result interface of the validate function. */\n  export type Result<Output> = SuccessResult<Output> | FailureResult\n\n  /** The result interface if validation succeeds. */\n  export interface SuccessResult<Output> {\n    /** The typed output value. */\n    readonly value: Output\n    /** The non-existent issues. */\n    readonly issues?: undefined\n  }\n\n  /** The result interface if validation fails. */\n  export interface FailureResult {\n    /** The issues of failed validation. */\n    readonly issues: ReadonlyArray<Issue>\n  }\n\n  /** The issue interface of the failure output. */\n  export interface Issue {\n    /** The error message of the issue. */\n    readonly message: string\n    /** The path of the issue, if any. */\n    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined\n  }\n\n  /** The path segment interface of the issue. */\n  export interface PathSegment {\n    /** The key representing a path segment. */\n    readonly key: PropertyKey\n  }\n\n  /** The Standard Schema types interface. */\n  export interface Types<Input = unknown, Output = Input> {\n    /** The input type of the schema. */\n    readonly input: Input\n    /** The output type of the schema. */\n    readonly output: Output\n  }\n\n  /** Infers the input type of a Standard Schema. */\n  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input']\n\n  /** Infers the output type of a Standard Schema. */\n  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output']\n}\n"
+// codegen:end
+
+// codegen:start {preset: str, source: ../standard-schema/errors.ts, const: standardSchemaV1ErrorsSrc, excludeLines: ['^import']}
+const standardSchemaV1ErrorsSrc =
+  "\nexport const prettifyStandardSchemaError = (error: unknown): string | null => {\n  if (!looksLikeStandardSchemaFailure(error)) return null\n\n  const issues = [...error.issues]\n    .map(issue => {\n      const path = issue.path || []\n      const primitivePathSegments = path.map(segment => {\n        if (typeof segment === 'string' || typeof segment === 'number' || typeof segment === 'symbol') return segment\n        return segment.key\n      })\n      const dotPath = toDotPath(primitivePathSegments)\n      return {\n        issue,\n        path,\n        primitivePathSegments,\n        dotPath,\n      }\n    })\n    .sort((a, b) => a.path.length - b.path.length)\n\n  const lines: string[] = []\n\n  for (const {issue, dotPath} of issues) {\n    let message = `✖ ${issue.message}`\n    if (dotPath) message += ` → at ${dotPath}`\n    lines.push(message)\n  }\n\n  return lines.join('\\n')\n}\n\nexport function toDotPath(path: (string | number | symbol)[]): string {\n  const segs: string[] = []\n  for (const seg of path) {\n    if (typeof seg === 'number') segs.push(`[${seg}]`)\n    else if (typeof seg === 'symbol') segs.push(`[${JSON.stringify(String(seg))}]`)\n    else if (/[^\\w$]/.test(seg)) segs.push(`[${JSON.stringify(seg)}]`)\n    else {\n      if (segs.length) segs.push('.')\n      segs.push(seg)\n    }\n  }\n\n  return segs.join('')\n}\n\nexport class StandardSchemaV1Error extends Error implements StandardSchemaV1.FailureResult {\n  issues: StandardSchemaV1.FailureResult['issues']\n  constructor(failure: StandardSchemaV1.FailureResult, options?: {cause?: Error}) {\n    super('Standard Schema error - details in `issues`.', options)\n    this.issues = failure.issues\n  }\n}\n"
+// codegen:end
+
+// codegen:start {preset: str, source: ../standard-schema/utils.ts, const: standardSchemaV1UtilsSrc, excludeLines: ['^import']}
+const standardSchemaV1UtilsSrc =
+  "\nexport const looksLikeStandardSchemaFailure = (error: unknown): error is StandardSchemaV1.FailureResult => {\n  return !!error && typeof error === 'object' && 'issues' in error && Array.isArray(error.issues)\n}\n\nexport const looksLikeStandardSchema = (thing: unknown): thing is StandardSchemaV1 => {\n  return !!thing && typeof thing === 'object' && '~standard' in thing && typeof thing['~standard'] === 'object'\n}\n"
+// codegen:end

src/presets/str.ts

@@ -0,0 +1,99 @@
+import {definePreset} from './util/standard-schema-preset'
+
+/**
+ * Copies a whole other file into a const variable. Useful for capturing a file's full contents as a hard-coded string.
+ * Obviously this creates duplicated data, so use judiciously!
+ *
+ * ##### basic usage
+ * ```js
+ * // codegen:start {preset: copy, source: ../../another-project/src/some-file.ts}
+ * import {z} from 'zod'
+ * export const MyObject = z.object({ foo: z.string() })
+ * // codegen:end
+ * ```
+ *
+ * #### excludeLines
+ *
+ * ```ts
+ * ;
+ * import {z} from 'zod/v4' // in this project we use zod v4, but we're copying from a project that uses zod v3
+ * // codegen:start {preset: copy, source: ../../another-project/src/some-file.ts, excludeLines: ['^import']}
+ * ;
+ * export const MyObject = z.object({ foo: z.string() })
+ * // codegen:end
+ * ```
+ *
+ * #### onlyIfExists
+ * ```js
+ * // copy a file from a sibling project, but only if the sibling project actually exists
+ * // in this case this will effectively skip the copying step on machines that don't have the sibling project installed
+ * // e.g. on CI runners.
+ * // codegen:start {preset: copy, source: ../../another-project/src/some-file.ts, onlyIfExists: ../../another-project/package.json}
+ * ;
+ * import {z} from 'zod'
+ * ;
+ * export const MyObject = z.object({ foo: z.string() });
+ * ;
+ * // codegen:end
+ * ```
+ *
+ * #### comparison
+ * ```js
+ * // by default, the content will perform a "simplified" comparison with existing content, so differences from tools like prettier
+ * // are ignored. if you care about whitespace and similar differences, you can set the comparison option to `strict`.
+ * // codegen:start {preset: copy, source: ../../another-project/src/some-file.ts, comparison: strict}
+ * ;
+ * import {z} from "zod"
+ * ;
+ * export const MyObject = z.object({ foo: z.string() })
+ * ;
+ * // codegen:end
+ * ```
+ */
+export const str = definePreset(
+  {
+    source: 'string',
+    const: 'string',
+    'export?': 'boolean',
+    /** path to the file to copy. can be absolute or relative to the file being linted */
+    /** if provided, only runs if this file exists - if it's missing, the existing content is returned (defaulting to empty string) */
+    'onlyIfExists?': 'string',
+    /** if provided, these lines will be removed from the copied content. e.g. `excludeLines: ['^import', '// codegen:']` */
+    'excludeLines?': 'string[]',
+    /**
+     * if set to `strict` the content will update if it's not a perfect match. by default (`simplified`) it will only update
+     * if the "simplified" version of the content is different.
+     */
+    'comparison?': '"simplified" | "strict"',
+  },
+  ({options, meta, context, dependencies: {fs, path, simplify}}) => {
+    // todo: add an option to allow syncing the other way - that is, if the content on the file being linted is newer,
+    // don't autofix - offer two suggestions: 1) write to the source file, 2) write to the file being linted.
+    const getAbsolutePath = (filepath: string) => path.resolve(path.dirname(context.physicalFilename), filepath)
+    const shouldRun = options.onlyIfExists ? fs.existsSync(getAbsolutePath(options.onlyIfExists)) : true
+    if (!shouldRun) return meta.existingContent || ''
+
+    let content = fs.readFileSync(getAbsolutePath(options.source), 'utf8')
+    if (options.excludeLines) {
+      const regexes = options.excludeLines.map(line => new RegExp(line))
+      const lines = content.split('\n')
+      content = lines.filter(line => !regexes.some(regex => regex.test(line))).join('\n')
+    }
+
+    content = `const ${options.const} = ${JSON.stringify(content)}`
+    if (options.export) content = `export ${content}`
+
+    let isUpToDate: boolean
+    // eslint-disable-next-line unicorn/prefer-ternary
+    if (!options.comparison || options.comparison === 'simplified') {
+      // we only want to declare it outdated if the simplified versions are different
+      isUpToDate = simplify.equivalentSimplified(content, meta.existingContent)
+    } else {
+      isUpToDate = content === meta.existingContent
+    }
+
+    if (isUpToDate) return meta.existingContent || ''
+
+    return content
+  },
+)

src/presets/util/standard-schema-preset.ts

@@ -1,6 +1,11 @@
 import {Preset} from '../..'
 import {arktype} from '../../esm-modules'
-import {StandardSchemaV1, looksLikeStandardSchemaFailure, prettifyStandardSchemaError} from '../../standard-schema'
+import {
+  StandardSchemaV1,
+  looksLikePromise,
+  looksLikeStandardSchemaFailure,
+  prettifyStandardSchemaError,
+} from '../../standard-schema'
 
 type $ = {}
 /** define a preset using an arktype schema definition. note that you don't have to import arktype */
@@ -32,11 +37,11 @@ const definePresetFromStandardSchema = <Input extends {}, Output extends {} = In
 ): Preset<Output> => {
   return params => {
     const result = schema['~standard'].validate(params.options)
-    if (result instanceof Promise) {
+    if (looksLikePromise(result)) {
       throw new Error('Standard Schema validation is async')
     }
     if (looksLikeStandardSchemaFailure(result)) {
-      throw new Error(`Invalid options: ${prettifyStandardSchemaError(result.issues)}`)
+      throw new Error(`Invalid options: ${prettifyStandardSchemaError(result)}`)
     }
     return fn({...params, options: result.value as never})
   }

src/standard-schema.ts

@@ -63,6 +63,10 @@ export declare namespace StandardSchemaV1 {
   export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output']
 }
 
+export const looksLikePromise = (error: unknown): error is Promise<unknown> => {
+  return !!error && typeof error === 'object' && 'then' in error && typeof error.then === 'function'
+}
+
 export const looksLikeStandardSchemaFailure = (error: unknown): error is StandardSchemaV1.FailureResult => {
   return !!error && typeof error === 'object' && 'issues' in error && Array.isArray(error.issues)
 }
@@ -71,9 +75,12 @@ export const looksLikeStandardSchema = (thing: unknown): thing is StandardSchema
   return !!thing && typeof thing === 'object' && '~standard' in thing && typeof thing['~standard'] === 'object'
 }
 
-export const prettifyStandardSchemaError = (error: unknown): string | null => {
+export const prettifyErrorIfStandardSchema = (error: unknown): string | null => {
   if (!looksLikeStandardSchemaFailure(error)) return null
+  return prettifyStandardSchemaError(error)
+}
 
+export const prettifyStandardSchemaError = (error: StandardSchemaV1.FailureResult): string | null => {
   const issues = [...error.issues]
     .map(issue => {
       const path = issue.path || []

src/standard-schema/contract.ts

@@ -0,0 +1,66 @@
+// from https://github.com/standard-schema/standard-schema
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1
+    /** The vendor name of the schema library. */
+    readonly vendor: string
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output
+    /** The non-existent issues. */
+    readonly issues?: undefined
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input
+    /** The output type of the schema. */
+    readonly output: Output
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input']
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output']
+}

src/standard-schema/errors.ts

@@ -0,0 +1,56 @@
+import type {StandardSchemaV1} from './contract'
+import {looksLikeStandardSchemaFailure} from './utils'
+
+export const prettifyStandardSchemaError = (error: unknown): string | null => {
+  if (!looksLikeStandardSchemaFailure(error)) return null
+
+  const issues = [...error.issues]
+    .map(issue => {
+      const path = issue.path || []
+      const primitivePathSegments = path.map(segment => {
+        if (typeof segment === 'string' || typeof segment === 'number' || typeof segment === 'symbol') return segment
+        return segment.key
+      })
+      const dotPath = toDotPath(primitivePathSegments)
+      return {
+        issue,
+        path,
+        primitivePathSegments,
+        dotPath,
+      }
+    })
+    .sort((a, b) => a.path.length - b.path.length)
+
+  const lines: string[] = []
+
+  for (const {issue, dotPath} of issues) {
+    let message = `✖ ${issue.message}`
+    if (dotPath) message += ` → at ${dotPath}`
+    lines.push(message)
+  }
+
+  return lines.join('\n')
+}
+
+export function toDotPath(path: (string | number | symbol)[]): string {
+  const segs: string[] = []
+  for (const seg of path) {
+    if (typeof seg === 'number') segs.push(`[${seg}]`)
+    else if (typeof seg === 'symbol') segs.push(`[${JSON.stringify(String(seg))}]`)
+    else if (/[^\w$]/.test(seg)) segs.push(`[${JSON.stringify(seg)}]`)
+    else {
+      if (segs.length) segs.push('.')
+      segs.push(seg)
+    }
+  }
+
+  return segs.join('')
+}
+
+export class StandardSchemaV1Error extends Error implements StandardSchemaV1.FailureResult {
+  issues: StandardSchemaV1.FailureResult['issues']
+  constructor(failure: StandardSchemaV1.FailureResult, options?: {cause?: Error}) {
+    super('Standard Schema error - details in `issues`.', options)
+    this.issues = failure.issues
+  }
+}

src/standard-schema/utils.ts

@@ -0,0 +1,9 @@
+import type {StandardSchemaV1} from './contract'
+
+export const looksLikeStandardSchemaFailure = (error: unknown): error is StandardSchemaV1.FailureResult => {
+  return !!error && typeof error === 'object' && 'issues' in error && Array.isArray(error.issues)
+}
+
+export const looksLikeStandardSchema = (thing: unknown): thing is StandardSchemaV1 => {
+  return !!thing && typeof thing === 'object' && '~standard' in thing && typeof thing['~standard'] === 'object'
+}