Programmatic API

In many cases it's useful to start Platformatic Service using an API instead of command line, e.g. in tests we want to start and stop our server.

The buildServer function allows that:

import { buildServer } from '@platformatic/service'

const app = await buildServer('path/to/platformatic.service.json')

await app.start()

const res = await fetch(app.url)
console.log(await res.json())

// do something

await app.close()

It is also possible to customize the configuration:

import { buildServer } from '@platformatic/service'

const app = await buildServer({
  server: {
    hostname: '127.0.0.1',
    port: 0
  }
})

await app.start()

const res = await fetch(app.url)
console.log(await res.json())

// do something

await app.close()

Creating a reusable application on top of Platformatic Service

Platformatic DB is built on top of Platformatic Serivce. If you want to build a similar kind of tool, follow this example:

import { buildServer, schema } from '@platformatic/service'
import { readFileSync } from 'node:fs'

async function myPlugin (app, opts) {
  // app.platformatic.configManager contains an instance of the ConfigManager
  console.log(app.platformatic.configManager.current)

  await app.register(platformaticService, opts)
}

// break Fastify encapsulation
myPlugin[Symbol.for('skip-override')] = true
myPlugin.configType = 'myPlugin'

// This is the schema for this reusable application configuration file,
// customize at will but retain the base properties of the schema from
// @platformatic/service
myPlugin.schema = schema

// The configuration of the ConfigManager
myPlugin.configManagerConfig = {
  version: JSON.parse(readFileSync(new URL(import.meta.url, 'package.json'))).version
  schema: foo.schema,
  allowToWatch: ['.env'],
  schemaOptions: {
    useDefaults: true,
    coerceTypes: true,
    allErrors: true,
    strict: false
  },
  async transformConfig () {
    console.log(this.current) // this is the current config

    // In this method you can alter the configuration before the application
    // is started. It's useful to apply some defaults that cannot be derived
    // inside the schema, such as resolving paths.
  }
}


const server = await buildServer('path/to/config.json', myPlugin)

await server.start()

const res = await fetch(server.listeningOrigin)
console.log(await res.json())

// do something

await service.close()

If you want to provide functionality before the plugins are loaded, but after metrics and telemetry are in place, you can use the beforePlugins option:

async function myPlugin (app, opts) {
  await app.register(platformaticService, {
    ...opts,
    beforePlugins: [async function (app) {
      app.decorate('myvalue', 42)
    }]
  })
}

TypeScript support

In order for this module to work on a TypeScript setup (outside of an application created with create-platformatic), you have to add the following to your types:

import { FastifyInstance } from 'fastify'
import { PlatformaticApp, PlatformaticServiceConfig } from '@platformatic/service'

declare module 'fastify' {
  interface FastifyInstance {
    platformatic: PlatformaticApp<PlatformaticServiceConfig>
  }
}

Then, you can use it:

/// <reference path="./global.d.ts" />
import { FastifyInstance } from 'fastify'

export default async function (app: FastifyInstance) {
  app.get('/', async () => {
    return app.platformatic.config
  })
}

You can always generate a file called global.d.ts with the above content via the platformatic service types command.

Usage with custom configuration

If you are creating a reusable application on top of Platformatic Service, you would need to create the types for your schema, using json-schema-to-typescript in a ./config.d.ts file and use it like so:

import { FastifyInstance } from 'fastify'
import { PlatformaticApp } from '@platformatic/service'
import { YourApp } from './config'

declare module 'fastify' {
  interface FastifyInstance {
    platformatic: PlatformaticApp<YourApp>
  }
}

Note that you can construct platformatic like any other union types, adding other definitions.

Writing a custom Stackable with TypeScript

Creating a reusable application with TypeScript requires a bit of setup. First, create a schema.ts file that generates the JSON Schema for your your application. Like so:

import { schema as serviceSchema } from '@platformatic/service'
import esMain from 'es-main'

const baseSchema = serviceSchema.schema

export const schema = structuredClone(baseSchema)

schema.$id = 'https://raw.githubusercontent.com/platformatic/acme-base/main/schemas/1.json'
schema.title = 'Acme Base'

// Needed to specify the extended module 
schema.properties.extends = {
  type: 'string'
}

schema.properties.dynamite = {
  anyOf: [{
    type: 'boolean'
  }, {
    type: 'string'
  }],
  description: 'Enable /dynamite route'
}

delete schema.properties.plugins

if (esMain(import.meta)) {
  console.log(JSON.stringify(schema, null, 2))
}

Then generates the matching types with json-schema-to-typescript:

1. tsc && node dist/lib/schema.js > schemas/acme.json
2. json2ts < schemas/acme.json > src/lib/config.d.ts

Finally, you can write the actual reusable application:

import fp from 'fastify-plugin'
import { platformaticService, buildServer as buildServiceServer, Stackable, PlatformaticServiceConfig } from '@platformatic/service'
import { schema } from './schema.js'
import { FastifyInstance } from 'fastify'
import type { ConfigManager } from '@platformatic/config'
import type { AcmeBase as AcmeBaseConfig } from './config.js'
import { readFileSync } from 'node:fs'

export interface AcmeBaseMixin {
  platformatic: {
    configManager: ConfigManager<AcmeBaseConfig>,
    config: AcmeBaseConfig
  }
}

async function isDirectory (path: string) {
  try {
    return (await lstat(path)).isDirectory()
  } catch {
    return false
  }
}

function buildStackable () : Stackable<AcmeBaseConfig> {
  async function acmeBase (_app: FastifyInstance, opts: object) {
    // Needed to avoid declaration mergin and be compatibile with the
    // Fastify types
    const app = _app as FastifyInstance & AcmeBaseMixin

    await app.register(platformaticService, opts)
  }

  // break Fastify encapsulation
  fp(acmeBase)

  acmeBase.configType = 'acmeBase'

  // This is the schema for this reusable application configuration file,
  // customize at will but retain the base properties of the schema from
  // @platformatic/service
  acmeBase.schema = schema

  // The configuration of the ConfigManager
  acmeBase.configManagerConfig = {
    schema,
    version: require('./package.json').version
    //// use the following if the file is compiled as ESM:
    // version: JSON.parse(readFileSync(new URL(import.meta.url, 'package.json'))).version
    allowToWatch: ['.env'],
    schemaOptions: {
      useDefaults: true,
      coerceTypes: true,
      allErrors: true,
      strict: false
    },
    async transformConfig (this: ConfigManager<AcmeBaseConfig & PlatformaticServiceConfig>) {
      // Call the transformConfig method from the base stackable
      platformaticService.configManagerConfig.transformConfig.call(this)

      // In this method you can alter the configuration before the application
      // is started. It's useful to apply some defaults that cannot be derived
      // inside the schema, such as resolving paths.
    }
  }

  return acmeBase
}

export const acmeBase = buildStackable()

export default acmeBase

export async function buildServer (opts: object) {
  return buildServiceServer(opts, acmeBase)
}

Implement auto-upgrade of the configuration

Platformatic support auto-upgrading the configuration of your stackable to the latest version. This enables the use of compatibility options to turn on and off individual features. Imagine that you want to change the default behavior of your stackable: you can add a configuration option to set the previous behavior. Then during the upgrade logic, you only have to add this new configuration.

The key to implement this logic is semgrator. semgrator run migrations code based on semantic version rules. So on a breaking/behavior change that results in a new compatibility option in your configuration file, you can add a new migration rule that set the new option to false automatically.

Writing migrations

export const migration = {
  version: '1.0.0',
  up: (input) => {
    // Do something with Config
    return input
  },
}

Wiring it to the stackable

You just need to add a version string (the current module version, as specified in package.json) and upgrade function into your configManagerConfig:

const { join } = require('path')
const pkg = require('../package.json')

async function upgrade (config, version) {
  const { semgrator } = await import('semgrator')

  const iterator = semgrator({
    version,
    path: join(__dirname, 'versions'),
    input: config,
    logger: this.logger
  })

  let result

  for await (const updated of iterator) {
    // You can add a console.log here to know what is updated
    result = updated.result
  }

  return result
}

stackable.configManagerConfig = {
  ...
  version: require('./package.json'),
  upgrade
}