fastify-ata 0.3.1 → 0.4.0

package/compat/ata-default-preload.js

@@ -0,0 +1,24 @@
+'use strict'
+
+// Preload that makes Fastify use ata as its GLOBAL default validator, by
+// intercepting the single `require('@fastify/ajv-compiler')` in Fastify's
+// schema-controller and returning the ata factory instead.
+//
+// Usage (from a Fastify checkout):
+//   node --require /abs/path/fastify-ata/compat/ata-default-preload.js \
+//        --test test/schema-validation.test.js
+//
+// Tests that build their own AJV instance (require('ajv')) or set a custom
+// validatorCompiler bypass this and keep using AJV, as they should.
+
+const Module = require('module')
+const path = require('path')
+const AtaCompiler = require(path.join(__dirname, '..', 'compiler'))
+
+const origLoad = Module._load
+Module._load = function (request, parent, isMain) {
+  if (request === '@fastify/ajv-compiler') {
+    return AtaCompiler
+  }
+  return origLoad.apply(this, arguments)
+}

package/compiler.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const { Validator } = require('ata-validator')
+
+// @fastify/ajv-compiler-compatible factory so ata can be installed as
+// Fastify's global default validator:
+//
+//   Fastify({ schemaController: { compilersFactory: { buildValidator: AtaCompiler() } } })
+//
+// Shape mirrors @fastify/ajv-compiler:
+//   AtaCompiler() -> buildCompilerFromPool(externalSchemas, options)
+//                 -> buildValidatorFunction({ schema }) -> validate(data)
+
+function AtaCompiler() {
+  return function buildCompilerFromPool(externalSchemas, options) {
+    const customOptions = (options && options.customOptions) || {}
+    // Default to Fastify's default AJV behavior: coerce (array mode, so a scalar
+    // becomes a single-element array), apply defaults, strip undeclared
+    // properties. Honor explicit overrides, preserving the 'array' mode value.
+    const coerceTypes = customOptions.coerceTypes !== undefined ? customOptions.coerceTypes : 'array'
+    const removeAdditional = customOptions.removeAdditional !== undefined ? !!customOptions.removeAdditional : true
+    // Fastify's default AJV runs with allErrors: false, reporting only the
+    // first violation. Mirror that unless the caller opts into allErrors. ata's
+    // abortEarly returns a stub error, so instead collect fully and expose the
+    // first real error to keep its message and rich fields intact.
+    const firstErrorOnly = customOptions.allErrors !== true
+    const hasCoercion = coerceTypes || removeAdditional
+
+    const validatorOpts = {
+      schemas: externalSchemas,
+      coerceTypes,
+      removeAdditional,
+    }
+
+    return function buildValidatorFunction({ schema }) {
+      const validator = new Validator(schema, validatorOpts)
+      function validate(data) {
+        const result = validator.validate(data)
+        if (result.valid) {
+          validate.errors = null
+          return hasCoercion ? { value: data } : true
+        }
+        validate.errors = firstErrorOnly ? [result.errors[0]] : result.errors
+        return false
+      }
+      validate.errors = null
+      return validate
+    }
+  }
+}
+
+module.exports = AtaCompiler
+module.exports.AtaCompiler = AtaCompiler
+module.exports.default = AtaCompiler

package/index.d.ts

@@ -1,4 +1,5 @@
-import { FastifyPluginCallback } from 'fastify'
+import { FastifyPluginCallback, FastifyTypeProvider } from 'fastify'
+import { Infer, JSONSchema } from 'ata-validator'
 
 interface FastifyAtaOptions {
   /** Convert "42" -> 42 for integer fields, etc. */
@@ -11,8 +12,26 @@ interface FastifyAtaOptions {
    * only care about reject/accept.
    */
   abortEarly?: boolean
+  /**
+   * Install a schema error formatter that renders compiler-grade messages,
+   * including the ATA error code and a did-you-mean suggestion when available.
+   * Off by default to preserve AJV-compatible error messages.
+   */
+  prettyErrors?: boolean
 }
 
-declare const fastifyAta: FastifyPluginCallback<FastifyAtaOptions>
+declare namespace fastifyAta {
+  /**
+   * Fastify type provider backed by ata's `Infer<S>`. Use with
+   * `Fastify().withTypeProvider<fastifyAta.AtaTypeProvider>()` and author route
+   * schemas with `defineSchema(...)` from ata-validator so `request.body`,
+   * `request.query`, etc. are typed from the schema with no manual annotation.
+   */
+  interface AtaTypeProvider extends FastifyTypeProvider {
+    validator: this['schema'] extends JSONSchema ? Infer<this['schema']> : unknown
+    serializer: this['schema'] extends JSONSchema ? Infer<this['schema']> : unknown
+  }
+}
 
+declare const fastifyAta: FastifyPluginCallback<FastifyAtaOptions>
 export = fastifyAta

package/index.js

@@ -3,6 +3,18 @@
 const fp = require('fastify-plugin')
 const { Validator } = require('ata-validator')
 
+function prettyFormat(errors, dataVar) {
+  const message = errors.map((e) => {
+    let line = `${dataVar}${e.instancePath || ''} ${e.message}`
+    if (e.code) line += ` [${e.code}]`
+    if (e.suggestion && e.suggestion.text) line += ` (${e.suggestion.text})`
+    return line
+  }).join(', ')
+  const err = new Error(message)
+  err.statusCode = 400
+  return err
+}
+
 function fastifyAta(fastify, opts, done) {
   const cache = new WeakMap()
   const hasCoercion = !!(opts.coerceTypes || opts.removeAdditional)
@@ -12,6 +24,10 @@ function fastifyAta(fastify, opts, done) {
     abortEarly: opts.abortEarly || false,
   }
 
+  if (opts.prettyErrors) {
+    fastify.setSchemaErrorFormatter(prettyFormat)
+  }
+
   fastify.setValidatorCompiler(({ schema }) => {
     let validator = cache.get(schema)
     if (!validator) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "fastify-ata",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Fastify plugin for ata-validator. Runtime-competitive with the default, 24x faster serverless cold start, Standard Schema V1.",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js && node test-pretty-errors.js && node test-standalone.js && node test-compiler.js && node test-type-provider.js && tsc -p tsconfig.types.json"
   },
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/ata-core/fastify-ata#readme",
   "dependencies": {
-    "ata-validator": "^0.12.2",
+    "ata-validator": "^0.17.0",
     "fastify-plugin": "^5.1.0",
     "sanitize-filename": "^1.6.4"
   },
@@ -34,7 +34,9 @@
     "fastify": ">=4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^25.9.1",
     "autocannon": "^8.0.0",
-    "fastify": "^5.8.4"
+    "fastify": "^5.8.4",
+    "typescript": "^6.0.3"
   }
 }

package/standalone.js

@@ -73,13 +73,7 @@ function wrapValidator(validateFn) {
         validate.errors = null
         return true
       }
-      validate.errors = result.errors.map(e => ({
-        message: e.message,
-        instancePath: e.path || '',
-        schemaPath: '',
-        keyword: e.code || 'validation',
-        params: {},
-      }))
+      validate.errors = result.errors
       return false
     }
     // Boolean result

package/test-compiler.js

@@ -0,0 +1,69 @@
+'use strict'
+
+// Tests the @fastify/ajv-compiler-compatible factory so ata can serve as
+// Fastify's GLOBAL default validator (not just a per-route compiler).
+
+const Fastify = require('fastify')
+const AtaCompiler = require('./compiler')
+
+let pass = 0
+let fail = 0
+
+function assert(cond, msg) {
+  if (cond) { pass++; console.log(`  PASS  ${msg}`) }
+  else { fail++; console.log(`  FAIL  ${msg}`) }
+}
+
+async function run() {
+  console.log('\nfastify-ata compiler (global default) Tests\n')
+
+  // Factory shape mirrors @fastify/ajv-compiler: factory() -> build(ext, opts) -> compile({schema}) -> validate
+  const factory = AtaCompiler()
+  const build = factory({}, { customOptions: {} })
+  const validate = build({ schema: { type: 'object', properties: { n: { type: 'integer' } }, required: ['n'] } })
+  assert(validate({ n: 1 }) === true || (validate({ n: 1 }) && validate({ n: 1 }).value), 'compiler: valid input accepted')
+  const bad = validate({})
+  assert(bad === false, 'compiler: invalid input rejected')
+  assert(validate.errors && validate.errors[0].code, `compiler: rich errors present (got ${JSON.stringify(validate.errors && validate.errors[0])})`)
+
+  // As Fastify's GLOBAL default via schemaController, with cross-schema $ref
+  const app = Fastify({
+    schemaController: { compilersFactory: { buildValidator: AtaCompiler() } },
+  })
+  app.addSchema({ $id: 'addr', type: 'object', properties: { city: { type: 'string' } }, required: ['city'] })
+  app.post('/u', {
+    schema: {
+      body: {
+        type: 'object',
+        properties: { name: { type: 'string' }, address: { $ref: 'addr#' } },
+        required: ['name', 'address'],
+      },
+    },
+  }, (req, reply) => reply.send({ ok: true }))
+  await app.ready()
+
+  const okRes = await app.inject({ method: 'POST', url: '/u', payload: { name: 'M', address: { city: 'IST' } } })
+  assert(okRes.statusCode === 200, `compiler: cross-schema $ref valid -> 200 (got ${okRes.statusCode})`)
+
+  const badRes = await app.inject({ method: 'POST', url: '/u', payload: { name: 'M', address: {} } })
+  assert(badRes.statusCode === 400, `compiler: cross-schema $ref invalid -> 400 (got ${badRes.statusCode})`)
+  await app.close()
+
+  // coerceTypes default on (matches Fastify default): querystring "5" -> 5
+  const app2 = Fastify({
+    schemaController: { compilersFactory: { buildValidator: AtaCompiler() } },
+  })
+  app2.get('/q', {
+    schema: { querystring: { type: 'object', properties: { limit: { type: 'integer' } }, required: ['limit'] } },
+  }, (req, reply) => reply.send({ limit: req.query.limit, typ: typeof req.query.limit }))
+  await app2.ready()
+  const qRes = await app2.inject({ method: 'GET', url: '/q?limit=5' })
+  assert(qRes.statusCode === 200, `compiler: coerced querystring -> 200 (got ${qRes.statusCode})`)
+  assert(JSON.parse(qRes.payload).typ === 'number', `compiler: querystring coerced to number (got ${qRes.payload})`)
+  await app2.close()
+
+  console.log(`\n${pass}/${pass + fail} tests passed\n`)
+  process.exit(fail > 0 ? 1 : 0)
+}
+
+run().catch((err) => { console.error(err); process.exit(1) })

package/test-pretty-errors.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const fastify = require('fastify')
+const fastifyAta = require('./index')
+
+let pass = 0
+let fail = 0
+
+function assert(cond, msg) {
+  if (cond) { pass++; console.log(`  PASS  ${msg}`) }
+  else { fail++; console.log(`  FAIL  ${msg}`) }
+}
+
+const schema = {
+  body: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      age: { type: 'integer' },
+    },
+    required: ['name'],
+  },
+}
+
+async function run() {
+  console.log('\nfastify-ata prettyErrors Tests\n')
+
+  // prettyErrors ON: 400 message carries the compiler-grade code + suggestion
+  const app = fastify()
+  await app.register(fastifyAta, { prettyErrors: true })
+  app.post('/u', { schema }, (req, reply) => reply.send({ ok: true }))
+  await app.ready()
+
+  const r = await app.inject({ method: 'POST', url: '/u', payload: { age: 5 } })
+  assert(r.statusCode === 400, `prettyErrors: invalid returns 400 (got ${r.statusCode})`)
+  const msg = JSON.parse(r.payload).message
+  assert(/ATA\d{4}/.test(msg), `prettyErrors: message carries error code (got "${msg}")`)
+  assert(msg.includes('did you mean'), `prettyErrors: message carries suggestion (got "${msg}")`)
+  await app.close()
+
+  // prettyErrors OFF (default): message stays AJV-compatible, no ATA code
+  const app2 = fastify()
+  await app2.register(fastifyAta)
+  app2.post('/u', { schema }, (req, reply) => reply.send({ ok: true }))
+  await app2.ready()
+
+  const r2 = await app2.inject({ method: 'POST', url: '/u', payload: { age: 5 } })
+  assert(r2.statusCode === 400, `default: invalid returns 400 (got ${r2.statusCode})`)
+  const msg2 = JSON.parse(r2.payload).message
+  assert(!/ATA\d{4}/.test(msg2), `default: message has no ATA code (got "${msg2}")`)
+  await app2.close()
+
+  console.log(`\n${pass}/${pass + fail} tests passed\n`)
+  process.exit(fail > 0 ? 1 : 0)
+}
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/test-standalone.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const StandaloneValidator = require('./standalone')
+
+let pass = 0
+let fail = 0
+
+function assert(cond, msg) {
+  if (cond) { pass++; console.log(`  PASS  ${msg}`) }
+  else { fail++; console.log(`  FAIL  ${msg}`) }
+}
+
+const schema = {
+  type: 'object',
+  properties: { name: { type: 'string' }, age: { type: 'integer' } },
+  required: ['name'],
+}
+
+function run() {
+  console.log('\nfastify-ata standalone error passthrough Tests\n')
+
+  const build = StandaloneValidator({ readMode: false, storeFunction() {} })()
+  const validate = build({ schema })
+
+  assert(validate({ name: 'x', age: 1 }) === true, 'standalone: valid input accepted')
+
+  const ok = validate({ age: 5 })
+  assert(ok === false, 'standalone: invalid input rejected')
+
+  const e = validate.errors[0]
+  assert(e.keyword === 'required', `standalone: keyword is the JSON Schema keyword, not the code (got "${e.keyword}")`)
+  assert(e.code === 'ATA7001', `standalone: rich code preserved (got "${e.code}")`)
+  assert(e.schemaPath === '#/required', `standalone: schemaPath preserved (got "${e.schemaPath}")`)
+  assert(e.params && e.params.missingProperty === 'name', `standalone: params preserved (got ${JSON.stringify(e.params)})`)
+  assert(e.suggestion && /did you mean/.test(e.suggestion.text), `standalone: suggestion preserved (got ${JSON.stringify(e.suggestion)})`)
+
+  console.log(`\n${pass}/${pass + fail} tests passed\n`)
+  process.exit(fail > 0 ? 1 : 0)
+}
+
+run()

package/test-type-provider.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const fastify = require('fastify')
+const fastifyAta = require('./index')
+const { defineSchema } = require('ata-validator')
+
+let pass = 0, fail = 0
+function assert(cond, msg) { if (cond) { pass++; console.log('  PASS ', msg) } else { fail++; console.log('  FAIL ', msg) } }
+
+async function run() {
+  console.log('\nfastify-ata type-provider runtime smoke\n')
+  const app = fastify().withTypeProvider()
+  await app.register(fastifyAta)
+  app.post('/u', {
+    schema: { body: defineSchema({ type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' } }, required: ['name'] }) },
+  }, (req, reply) => reply.send({ name: req.body.name }))
+  await app.ready()
+
+  const ok = await app.inject({ method: 'POST', url: '/u', payload: { name: 'Mert', age: 26 } })
+  assert(ok.statusCode === 200, `valid -> 200 (got ${ok.statusCode})`)
+  assert(JSON.parse(ok.payload).name === 'Mert', 'valid -> body usable in handler')
+
+  const bad = await app.inject({ method: 'POST', url: '/u', payload: { age: 26 } })
+  assert(bad.statusCode === 400, `missing required -> 400 (got ${bad.statusCode})`)
+  await app.close()
+
+  console.log(`\n${pass}/${pass + fail} passed\n`)
+  process.exit(fail > 0 ? 1 : 0)
+}
+run().catch((e) => { console.error(e); process.exit(1) })

package/test-types.ts

@@ -0,0 +1,38 @@
+// Type-level test. Compiled with `tsc -p tsconfig.types.json` (no emit).
+// A type error here = failure. Asserts the type provider narrows request types.
+import Fastify from 'fastify'
+import { defineSchema } from 'ata-validator'
+import fastifyAta = require('./index')
+type AtaTypeProvider = fastifyAta.AtaTypeProvider
+
+// exact-type equality helper
+type Expect<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+
+const app = Fastify().withTypeProvider<AtaTypeProvider>()
+
+app.post('/users', {
+  schema: {
+    body: defineSchema({
+      type: 'object',
+      properties: { name: { type: 'string' }, age: { type: 'integer' } },
+      required: ['name'],
+    }),
+  },
+}, async (req) => {
+  // body must narrow: name required string, age optional number
+  const _name: string = req.body.name
+  const _age: number | undefined = req.body.age
+  const _exact: Expect<typeof req.body, { name: string; age?: number }> = true
+  void _name; void _age; void _exact
+  return { ok: true }
+})
+
+app.get('/search', {
+  schema: {
+    querystring: defineSchema({ type: 'object', properties: { q: { type: 'string' } }, required: ['q'] }),
+  },
+}, async (req) => {
+  const _q: string = req.query.q
+  void _q
+  return { ok: true }
+})

package/tsconfig.types.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "ignoreDeprecations": "6.0",
+    "esModuleInterop": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "lib": ["ES2022"]
+  },
+  "include": ["test-types.ts"],
+  "exclude": ["node_modules"]
+}