feat: standalone mode

.github/workflows/ci.yml

@@ -15,3 +15,4 @@ jobs:
     uses: fastify/workflows/.github/workflows/plugins-ci.yml@v3
     with:
       license-check: true
+      lint: true

README.md

@@ -26,6 +26,94 @@ You can also override the default configuration by passing the [`serializerOpts`
 This module is already used as default by Fastify.
 If you need to provide to your server instance a different version, refer to [the official doc](https://www.fastify.io/docs/latest/Reference/Server/#schemacontroller).
 
+### fast-json-stringify Standalone
+
+`[email protected]` introduces the [standalone feature](https://github.com/fastify/fast-json-stringify#standalone) that let you to pre-compile your schemas and use them in your application for a faster startup.
+
+To use this feature, you must be aware of the following:
+
+1. You must generate and save the application's compiled schemas.
+2. Read the compiled schemas from the file and provide them back to your Fastify application.
+
+
+#### Generate and save the compiled schemas
+
+Fastify helps you to generate the serialization schemas functions and it is your choice to save them where you want.
+To accomplish this, you must use a new compiler: `@fastify/fast-json-stringify-compiler/standalone`.
+
+You must provide 2 parameters to this compiler:
+
+- `readMode: false`: a boolean to indicate that you want generate the schemas functions string.
+- `storeFunction`" a sync function that must store the source code of the schemas functions. You may provide an async function too, but you must manage errors.
+
+When `readMode: false`, **the compiler is meant to be used in development ONLY**.
+
+
+```js
+const factory = require('@fastify/fast-json-stringify-compiler/standalone')({
+  readMode: false,
+  storeFunction (routeOpts, schemaSerializationCode) {
+    // routeOpts is like: { schema, method, url, httpStatus }
+    // schemaSerializationCode is a string source code that is the compiled schema function
+    const fileName = generateFileName(routeOpts)
+    fs.writeFileSync(path.join(__dirname, fileName), schemaSerializationCode)
+  }
+})
+
+const app = fastify({
+  jsonShorthand: false,
+  schemaController: {
+    compilersFactory: {
+      buildSerializer: factory
+    }
+  }
+})
+
+// ... add all your routes with schemas ...
+
+app.ready().then(() => {
+  // at this stage all your schemas are compiled and stored in the file system
+  // now it is important to turn off the readMode
+})
+```
+
+#### Read the compiled schemas functions
+
+At this stage, you should have a file for every route's schema.
+To use them, you must use the `@fastify/fast-json-stringify-compiler/standalone` with the parameters:
+
+- `readMode: true`: a boolean to indicate that you want read and use the schemas functions string.
+- `restoreFunction`" a sync function that must return a function to serialize the route's payload.
+
+Important keep away before you continue reading the documentation:
+
+- when you use the `readMode: true`, the application schemas are not compiled (they are ignored). So, if you change your schemas, you must recompile them!
+- as you can see, you must relate the route's schema to the file name using the `routeOpts` object. You may use the `routeOpts.schema.$id` field to do so, it is up to you to define a unique schema identifier.
+
+```js
+const factory = require('@fastify/fast-json-stringify-compiler/standalone')({
+  readMode: true,
+  restoreFunction (routeOpts) {
+    // routeOpts is like: { schema, method, url, httpStatus }
+    const fileName = generateFileName(routeOpts)
+    return require(path.join(__dirname, fileName))
+  }
+})
+
+const app = fastify({
+  jsonShorthand: false,
+  schemaController: {
+    compilersFactory: {
+      buildSerializer: factory
+    }
+  }
+})
+
+// ... add all your routes with schemas as before...
+
+app.listen({ port: 3000 })
+```
+
 ### How it works
 
 This module provide a factory function to produce [Serializer Compilers](https://www.fastify.io/docs/latest/Reference/Server/#serializercompiler) functions.

package.json

@@ -5,9 +5,11 @@
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
+    "lint": "standard",
     "lint:fix": "standard --fix",
-    "unit": "tap --100 test/**/*.test.js",
-    "test": "standard && npm run unit && npm run test:typescript",
+    "unit": "tap test/**/*.test.js",
+    "test": "npm run unit && npm run test:typescript",
+    "posttest": "rimraf test/fjs-generated*.js",
     "test:typescript": "tsd"
   },
   "repository": {
@@ -23,6 +25,8 @@
   "homepage": "https://github.com/fastify/fast-json-stringify-compiler#readme",
   "devDependencies": {
     "fastify": "^4.0.0",
+    "rimraf": "^3.0.2",
+    "sanitize-filename": "^1.6.3",
     "standard": "^17.0.0",
     "tap": "^16.0.0",
     "tsd": "^0.22.0"

standalone.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const SerializerSelector = require('./index')
+
+function StandaloneSerializer (options = { readMode: true }) {
+  if (options.readMode === true && !options.restoreFunction) {
+    throw new Error('You must provide a restoreFunction options when readMode ON')
+  }
+
+  if (options.readMode !== true && !options.storeFunction) {
+    throw new Error('You must provide a storeFunction options when readMode OFF')
+  }
+
+  if (options.readMode === true) {
+    // READ MODE: it behalf only in the restore function provided by the user
+    return function wrapper () {
+      return function (opts) {
+        return options.restoreFunction(opts)
+      }
+    }
+  }
+
+  // WRITE MODE: it behalf on the default SerializerSelector, wrapping the API to run the Ajv Standalone code generation
+  const factory = SerializerSelector()
+  return function wrapper (externalSchemas, serializerOpts = {}) {
+    // to generate the serialization source code, this option is mandatory
+    serializerOpts.mode = 'standalone'
+
+    const compiler = factory(externalSchemas, serializerOpts)
+    return function (opts) { // { schema/*, method, url, httpPart */ }
+      const serializeFuncCode = compiler(opts)
+
+      options.storeFunction(opts, serializeFuncCode)
+
+      // eslint-disable-next-line no-new-func
+      return new Function(serializeFuncCode)
+    }
+  }
+}
+
+module.exports = StandaloneSerializer

test/plugin.test.js

@@ -25,9 +25,7 @@ const externalSchemas2 = Object.freeze({
   }
 })
 
-const fastifyFjsOptionsDefault = Object.freeze({
-  customOptions: {}
-})
+const fastifyFjsOptionsDefault = Object.freeze({})
 
 t.test('basic usage', t => {
   t.plan(1)

test/standalone.test.js

@@ -0,0 +1,213 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const t = require('tap')
+const fastify = require('fastify')
+const sanitize = require('sanitize-filename')
+
+const FjsStandaloneCompiler = require('../standalone')
+
+function generateFileName (routeOpts) {
+  return `/fjs-generated-${sanitize(routeOpts.schema.$id)}-${routeOpts.method}-${routeOpts.httpPart}-${sanitize(routeOpts.url)}.js`
+}
+
+t.test('errors', t => {
+  t.plan(2)
+  t.throws(() => {
+    FjsStandaloneCompiler()
+  }, 'missing restoreFunction')
+  t.throws(() => {
+    FjsStandaloneCompiler({ readMode: false })
+  }, 'missing storeFunction')
+})
+
+t.test('generate standalone code', t => {
+  t.plan(5)
+
+  const base = {
+    $id: 'urn:schema:base',
+    definitions: {
+      hello: { type: 'string' }
+    },
+    type: 'object',
+    properties: {
+      hello: { $ref: '#/definitions/hello' }
+    }
+  }
+
+  const refSchema = {
+    $id: 'urn:schema:ref',
+    type: 'object',
+    properties: {
+      hello: { $ref: 'urn:schema:base#/definitions/hello' }
+    }
+  }
+
+  const endpointSchema = {
+    schema: {
+      $id: 'urn:schema:endpoint',
+      $ref: 'urn:schema:ref'
+    }
+  }
+
+  const schemaMap = {
+    [base.$id]: base,
+    [refSchema.$id]: refSchema
+  }
+
+  const factory = FjsStandaloneCompiler({
+    readMode: false,
+    storeFunction (routeOpts, schemaSerializerCode) {
+      t.same(routeOpts, endpointSchema)
+      t.type(schemaSerializerCode, 'string')
+      fs.writeFileSync(path.join(__dirname, '/fjs-generated.js'), schemaSerializerCode)
+      t.pass('stored the serializer function')
+    }
+  })
+
+  const compiler = factory(schemaMap)
+  compiler(endpointSchema)
+  t.pass('compiled the endpoint schema')
+
+  t.test('usage standalone code', t => {
+    t.plan(3)
+    const standaloneSerializer = require('./fjs-generated')
+    t.ok(standaloneSerializer)
+
+    const valid = standaloneSerializer({ hello: 'world' })
+    t.same(valid, JSON.stringify({ hello: 'world' }))
+
+    const invalid = standaloneSerializer({ hello: [] })
+    t.same(invalid, '{"hello":""}')
+  })
+})
+
+t.test('fastify integration - writeMode', async t => {
+  t.plan(4)
+
+  const factory = FjsStandaloneCompiler({
+    readMode: false,
+    storeFunction (routeOpts, schemaSerializationCode) {
+      const fileName = generateFileName(routeOpts)
+      t.ok(routeOpts)
+      fs.writeFileSync(path.join(__dirname, fileName), schemaSerializationCode)
+      t.pass(`stored the serializer function ${fileName}`)
+    },
+    restoreFunction () {
+      t.fail('write mode ON')
+    }
+  })
+
+  const app = buildApp(factory)
+  await app.ready()
+})
+
+t.test('fastify integration - writeMode forces standalone', async t => {
+  t.plan(4)
+
+  const factory = FjsStandaloneCompiler({
+    readMode: false,
+    storeFunction (routeOpts, schemaSerializationCode) {
+      const fileName = generateFileName(routeOpts)
+      t.ok(routeOpts)
+      fs.writeFileSync(path.join(__dirname, fileName), schemaSerializationCode)
+      t.pass(`stored the serializer function ${fileName}`)
+    },
+    restoreFunction () {
+      t.fail('write mode ON')
+    }
+  })
+
+  const app = buildApp(factory, {
+    mode: 'not-standalone',
+    rounding: 'ceil'
+  })
+
+  await app.ready()
+})
+
+t.test('fastify integration - readMode', async t => {
+  t.plan(6)
+
+  const factory = FjsStandaloneCompiler({
+    readMode: true,
+    storeFunction () {
+      t.fail('read mode ON')
+    },
+    restoreFunction (routeOpts) {
+      const fileName = generateFileName(routeOpts)
+      t.pass(`restore the serializer function ${fileName}}`)
+      return require(path.join(__dirname, fileName))
+    }
+  })
+
+  const app = buildApp(factory)
+  await app.ready()
+
+  let res = await app.inject({
+    url: '/foo',
+    method: 'POST'
+  })
+  t.equal(res.statusCode, 200)
+  t.equal(res.payload, JSON.stringify({ hello: 'world' }))
+
+  res = await app.inject({
+    url: '/bar?lang=it',
+    method: 'GET'
+  })
+  t.equal(res.statusCode, 200)
+  t.equal(res.payload, JSON.stringify({ lang: 'en' }))
+})
+
+function buildApp (factory, serializerOpts) {
+  const app = fastify({
+    exposeHeadRoutes: false,
+    jsonShorthand: false,
+    schemaController: {
+      compilersFactory: {
+        buildSerializer: factory
+      }
+    },
+    serializerOpts
+  })
+
+  app.addSchema({
+    $id: 'urn:schema:foo',
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      id: { type: 'integer' }
+    }
+  })
+
+  app.post('/foo', {
+    schema: {
+      response: {
+        200: {
+          $id: 'urn:schema:response',
+          type: 'object',
+          properties: {
+            hello: { $ref: 'urn:schema:foo#/properties/name' }
+          }
+        }
+      }
+    }
+  }, () => { return { hello: 'world' } })
+
+  app.get('/bar', {
+    schema: {
+      response: {
+        200: {
+          $id: 'urn:schema:response:bar',
+          type: 'object',
+          properties: {
+            lang: { type: 'string', enum: ['it', 'en'] }
+          }
+        }
+      }
+    }
+  }, () => { return { lang: 'en' } })
+
+  return app
+}