@ata-project/unplugin 0.3.0 → 0.5.0

package/README.md

@@ -6,6 +6,11 @@ The generated module imports nothing. A small schema compiles to about 1.3 KB gz
 
 Schemas can be authored as `.json`, `.js` or `.ts`.
 
+It also compiles away `new Validator(schema)` in your own code wherever the schema
+is known at build time and the result is the same, so the runtime compiler stays
+out of the bundle: for the test entry, 122.5 KB gzipped becomes 16.7 KB. See
+[compileAway](#compileaway-keep-new-validator-drop-the-compiler).
+
 ## Install
 
 ```bash
@@ -145,12 +150,12 @@ Other sources (`.json` without the `.schema` suffix, `.js`, `.ts`) produce
 | `nameFromFile` | file name in PascalCase | Type name for schemas without `title` or `$id`. |
 | `root` | from the bundler | Where the globs resolve from. Vite's root, Webpack's and Rspack's `context` and esbuild's `absWorkingDir` are read; Rollup and Rolldown need it passed. |
 | `alias` | Vite's `resolve.alias` | Import aliases inside `.ts` schema files. tsconfig `paths` work without configuration. |
-| `compileAway` | `false` | Replace `new Validator(schema)` in your code with a validator compiled at build time, where that gives the same results. See below. Needs ata-validator 1.36.0. |
+| `compileAway` | `true` | Replace `new Validator(schema)` in your code with a validator compiled at build time, where that gives the same results. See below. Needs ata-validator 1.36.0; with an older version the runtime stays, and a warning is printed only if you set the option yourself. |
 
 ## compileAway: keep `new Validator`, drop the compiler
 
-With `compileAway: true`, code written against the runtime API is compiled at
-build time without being changed:
+Code written against the runtime API is compiled at build time without being
+changed. This is on by default; `compileAway: false` turns it off.
 
 ```js
 import { Validator } from 'ata-validator'
@@ -168,10 +173,14 @@ The plugin puts a compiled validator in place of the `new Validator(...)` call,
 and once nothing else in the file uses the `ata-validator` import, the import
 goes with it, so the runtime compiler is not in the bundle. For the three-schema
 entry in `test/fixtures/compile-away`, one of them with defaults, a minified Vite
-library build is 115.7 KB gzipped without it and 15.5 KB with it, on
-ata-validator 1.36.0. Across the 977 schemas of SchemaStore, 725 can be compiled
+library build is 122.5 KB gzipped without it and 16.7 KB with it (gzip level 9), on
+ata-validator 1.39.2. Across the 977 schemas of SchemaStore, 725 can be compiled
 away this way.
 
+Where the code only ever calls `isValidObject()` or `isValidJSON()`, the plugin
+uses a smaller wrapper without the error machinery (needs ata-validator 1.40.0):
+a small app that only asks for a boolean bundles to 2.1 KB gzipped.
+
 The replacement answers `validate()`, `isValidObject()`, `validateJSON()` and
 `isValidJSON()` as a `Validator` with default options does: the same verdicts,
 defaults filled in, `data` on success, and the same errors, enriched the same
@@ -192,7 +201,9 @@ otherwise:
   the runtime;
 - the result goes into a `const` that is not exported and is only used as
   `name.validate(...)`, `name.isValidObject(...)`, `name.validateJSON(...)` or
-  `name.isValidJSON(...)`;
+  `name.isValidJSON(...)`; the call may be wrapped in `withKeywords(...)` from
+  `@ata-project/keywords`, which then registers its keywords on the compiled
+  validator as it does on a `Validator` (needs ata-validator 1.40.0);
 - ata-validator can compile the schema to the same results. It declines custom
   `errorMessage`s and shapes its code generator cannot express, which the
   runtime answers with its interpreted engine.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ata-project/unplugin",
-  "version": "0.3.0",
-  "description": "Compile JSON, JS and TS schema files to ata-validator standalone modules at build time, in Vite, Webpack, Rollup, Rolldown, esbuild and Rspack.",
+  "version": "0.5.0",
+  "description": "Build-time JSON Schema for Vite, Webpack, Rollup, Rolldown, esbuild and Rspack. compileAway takes the runtime compiler out of the bundle.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -77,8 +77,9 @@
     "unplugin": "^3.3.0"
   },
   "devDependencies": {
+    "@ata-project/keywords": "^0.3.3",
     "@rspack/core": "^1.7.0",
-    "ata-validator": "^1.37.0",
+    "ata-validator": "^1.40.0",
     "esbuild": "^0.28.0",
     "rolldown": "^1.2.8",
     "rollup": "^4.60.0",

package/src/compile-away.js

@@ -163,26 +163,44 @@ function constantsOf(ast, id) {
 // `const name = new Validator(...)`, declared once, not exported, and used only
 // as `name.<method>(...)` with a supported method.
 function replaceableBinding(newExpr, ctx) {
-  const decl = newExpr.__parent
-  if (!decl || decl.type !== 'VariableDeclarator' || decl.init !== newExpr || decl.id.type !== 'Identifier') return null
+  let decl = newExpr.__parent
+  // `withKeywords(new Validator(schema))` from @ata-project/keywords: the
+  // wrapper takes the keywords' check the way a Validator does, so the inner
+  // call is replaced and withKeywords stays to register the check on it.
+  if (decl && decl.type === 'CallExpression' && ctx.withKeywords && ctx.extendChecks &&
+      decl.callee.type === 'Identifier' && decl.callee.name === ctx.withKeywords &&
+      ctx.declared.get(ctx.withKeywords) === 1 && decl.arguments.length === 1 && decl.arguments[0] === newExpr) {
+    decl = decl.__parent
+    if (!decl || decl.type !== 'VariableDeclarator' || decl.init !== newExpr.__parent) return null
+  }
+  if (!decl || decl.type !== 'VariableDeclarator' || decl.id.type !== 'Identifier') return null
+  if (decl.init !== newExpr && decl.init !== newExpr.__parent) return null
   const list = decl.__parent
   if (!list || list.type !== 'VariableDeclaration' || list.kind !== 'const') return null
   if (list.__parent && list.__parent.type === 'ExportNamedDeclaration') return null
   const name = decl.id.name
   if (ctx.declared.get(name) !== 1) return null
+  const methods = new Set()
   for (const r of ctx.refs) {
     if (r.node.name !== name) continue
     const p = r.parent
     const member = p && (p.type === 'MemberExpression' || p.type === 'OptionalMemberExpression') && r.key === 'object' && !p.computed && p.property.type === 'Identifier' && METHODS.has(p.property.name)
     const called = member && p.__parent && (p.__parent.type === 'CallExpression' || p.__parent.type === 'OptionalCallExpression') && p.__parent.callee === p
     if (!called) return null
+    methods.add(p.property.name)
   }
-  return name
+  return { name, methods }
 }
 
-function inlineModule(src, index) {
+// Code that only asks for a boolean never reads an error.
+const VERDICT_METHODS = new Set(['isValidObject', 'isValidJSON'])
+const verdictOnly = (methods) => [...methods].every((m) => VERDICT_METHODS.has(m))
+
+// A verdict-only module hands out isValid alone, so the error function inside
+// it is unreferenced and the bundler drops it.
+function inlineModule(src, index, verdict) {
   const body = src.split('\n').filter((l) => !/^export\s/.test(l)).join('\n')
-  return `const __ataCompiled${index} = (() => {\n${body}\nreturn { validate, isValid };\n})();\n`
+  return `const __ataCompiled${index} = (() => {\n${body}\nreturn ${verdict ? '{ isValid }' : '{ validate, isValid }'};\n})();\n`
 }
 
 // The options of `new Validator(schema, options)` as a third argument for
@@ -226,14 +244,24 @@ export function compileAway(code, id, ata) {
     }
   }
   if (!validatorName) return null
+  let withKeywords = null
+  for (const stmt of ast.program.body) {
+    if (stmt.type !== 'ImportDeclaration' || stmt.source.value !== '@ata-project/keywords' || stmt.importKind === 'type') continue
+    for (const sp of stmt.specifiers) {
+      if (sp.type !== 'ImportSpecifier' || sp.importKind === 'type') continue
+      const imported = sp.imported.type === 'Identifier' ? sp.imported.name : sp.imported.value
+      if (imported === 'withKeywords') withKeywords = sp.local.name
+    }
+  }
 
   const { declared, refs } = scan(ast)
   if (declared.get(validatorName) !== 1) return null
-  const ctx = { declared, refs, constants: constantsOf(ast, id), defineSchema }
+  const ctx = { declared, refs, constants: constantsOf(ast, id), defineSchema, withKeywords, extendChecks: ata.compiledExtendChecks === true }
 
   const s = new MagicString(code)
   const modules = []
   const done = new Set()
+  const wrappers = { full: false, verdict: false }
   for (const r of refs) {
     if (r.node.name !== validatorName) continue
     const expr = r.parent
@@ -244,15 +272,19 @@ export function compileAway(code, id, ata) {
       optionsArg = compiledOptionsArg(expr.arguments[1], ctx, supportedOptions)
       if (optionsArg === NOT_STATIC) continue
     }
-    if (!replaceableBinding(expr, ctx)) continue
+    const binding = replaceableBinding(expr, ctx)
+    if (!binding) continue
     const schema = staticValue(expr.arguments[0], ctx)
     if (schema === NOT_STATIC || schema === null || typeof schema !== 'object' || Array.isArray(schema)) continue
     let src = null
     try { src = compiledModuleFor(schema, { format: 'esm' }) } catch { src = null }
     if (!src) continue
     const index = modules.length
-    modules.push(inlineModule(src, index))
-    s.overwrite(expr.start, expr.end, `__ataFromCompiled(__ataCompiled${index}, ${JSON.stringify(compiledSchemaFor(schema))}${optionsArg ? ', ' + optionsArg : ''})`)
+    const verdict = ata.compiledVerdict === true && verdictOnly(binding.methods)
+    modules.push(inlineModule(src, index, verdict))
+    const wrap = verdict ? '__ataFromCompiledVerdict' : '__ataFromCompiled'
+    if (verdict) wrappers.verdict = true; else wrappers.full = true
+    s.overwrite(expr.start, expr.end, `${wrap}(__ataCompiled${index}, ${JSON.stringify(compiledSchemaFor(schema))}${optionsArg ? ', ' + optionsArg : ''})`)
     done.add(expr)
   }
   if (done.size === 0) return null
@@ -278,7 +310,8 @@ export function compileAway(code, id, ata) {
     const clause = [def ? text(def) : null, named.length ? `{ ${named.map(text).join(', ')} }` : null].filter(Boolean).join(', ')
     s.overwrite(importDecl.start, importDecl.end, `import ${clause} from ${code.slice(importDecl.source.start, importDecl.source.end)}`)
   }
-  s.prepend(`import { fromCompiled as __ataFromCompiled } from 'ata-validator/compiled';\n`)
+  if (wrappers.verdict) s.prepend(`import { fromCompiledVerdict as __ataFromCompiledVerdict } from 'ata-validator/compiled-verdict';\n`)
+  if (wrappers.full) s.prepend(`import { fromCompiled as __ataFromCompiled } from 'ata-validator/compiled';\n`)
   s.appendLeft(lastImportEnd, '\n' + modules.join(''))
   return { code: s.toString(), map: s.generateMap({ hires: true, source: id, includeContent: true }), replaced: done.size }
 }

package/src/core.js

@@ -41,7 +41,7 @@ const DEFAULT_OPTIONS = {
   format: 'esm',
   abortEarly: false,
   types: true,
-  compileAway: false,
+  compileAway: true,
   nameFromFile: (file) => {
     const base = path.basename(file, path.extname(file)).replace(/\.schema$/i, '')
     return pascal(base)
@@ -64,6 +64,24 @@ async function loadAta() {
   // compiledModuleFor exists from ata-validator 1.35.0; compile-away needs it
   // and is skipped with a warning when it is missing.
   const canCompileAway = typeof build.compiledModuleFor === 'function' && typeof build.compiledSchemaFor === 'function'
+  // The verdict-only wrapper, from ata-validator 1.40.0: code that never reads
+  // errors gets it and the error pipeline stays out of the bundle.
+  let compiledVerdict = false
+  if (canCompileAway) {
+    try { compiledVerdict = typeof (await import('ata-validator/compiled-verdict')).fromCompiledVerdict === 'function' } catch { compiledVerdict = false }
+  }
+  // Whether the wrappers take a check registered with _extendChecks, as
+  // withKeywords from @ata-project/keywords registers one; from 1.40.0. Asked
+  // of a wrapper itself, so an ata-validator without it keeps such calls on
+  // the runtime.
+  let compiledExtendChecks = false
+  if (canCompileAway) {
+    try {
+      const c = await import('ata-validator/compiled')
+      const fromCompiled = (c.default ?? c).fromCompiled ?? c.fromCompiled
+      compiledExtendChecks = typeof fromCompiled({ validate: () => ({ valid: true, errors: [] }), isValid: () => true }, {}, { useDefaults: false })._extendChecks === 'function'
+    } catch { compiledExtendChecks = false }
+  }
   return {
     ...api,
     toStandaloneModule: build.toStandaloneModule,
@@ -72,6 +90,8 @@ async function loadAta() {
     // The Validator options fromCompiled() reproduces, from ata-validator
     // 1.37.0; before it, only calls without options are replaced.
     compiledOptions: canCompileAway && Array.isArray(build.compiledOptions) ? build.compiledOptions : [],
+    compiledVerdict,
+    compiledExtendChecks,
   }
 }
 

package/src/index.d.ts

@@ -27,7 +27,7 @@ export interface Options {
    * only used through validate(), isValidObject(), validateJSON() and
    * isValidJSON(), so the runtime compiler stays out of the bundle. Results are
    * the ones the runtime gives. Needs ata-validator 1.35.0 or later.
-   * Default: `false`.
+   * Default: `true`; `false` turns it off.
    */
   compileAway?: boolean
 }

package/src/index.js

@@ -34,8 +34,11 @@ export const unpluginFactory = (userOptions = {}) => {
     // compileAway: `new Validator(schema)` with a schema the build can read
     // becomes a validator compiled here, and the runtime compiler leaves the
     // bundle. See src/compile-away.js for what is replaced and what is not.
+    // On unless the caller turned it off. It replaces a call only where the
+    // compiled validator answers exactly as the runtime would, so being on by
+    // default can cost a saving but not change a result.
     transformInclude(id) {
-      if (!userOptions.compileAway) return false
+      if (userOptions.compileAway === false) return false
       const file = id.split('?')[0]
       return SOURCE.test(file) && !file.split(/[\\/]/).includes('node_modules')
     },
@@ -44,7 +47,9 @@ export const unpluginFactory = (userOptions = {}) => {
       if (!code.includes('ata-validator')) return null
       const api = await session.api()
       if (!api.compiledModuleFor) {
-        if (!session.warnedCompileAway) {
+        // Only a caller who asked for it hears that it could not happen; on
+        // by default, an older ata-validator just keeps the runtime.
+        if (userOptions.compileAway === true && !session.warnedCompileAway) {
           session.warnedCompileAway = true
           session.logger?.warn?.('[unplugin-ata] compileAway needs ata-validator 1.36.0 or later; nothing was replaced')
         }