Kitten

See how to implement type safety for your databases by creating and using database app modules.

Topics covered

This is an advanced feature. Please feel free to skip this section and return to it later if you find it confusing.

You are not limited to using the default, untyped database Kitten sets up for you.

The default database, like many of the beautiful defaults in Kitten, exists to make it easy to get started with Kitten and use it to build quick Small Web places, teaching programming, etc.

If, however, you’re designing a Small Web place that you will need to maintain for a long period of time and/or that you are going to collaborate with others on, it would make sense to create your own database and to make it type safe so you get both errors and code completion during development time.

You can create your own custom database using a special type of app module called the database app module.

Learn more about App Modules.

Like any other app module, your database app module goes in the special app_modules directory in the root of your project. What’s special is that this app module must be called database with either a .js or .ts suffix.

In this example, we’re going to build an app that displays that names and ages of a number of kittens.

To begin, let’s create a new folder for our project and enter it:

mkdir kittens && cd kittens

Next let’s initialise a type-safe Kitten project in TypeScript using Kitten’s init command:

kitten init

This will run npm init if necessary, as well as install Kitten’s type-safety library (@small-web/kitten-types), add the recommended tsconfig.json file for Kitten projects, etc., to your project. The tsconfig.json file references a server and a client program, which are among the configuration files that the kitten init command writes (see tsconfig.json).

So far, we’ve only worked with JavaScript but Kitten also natively supports TypeScript without a build stage. In this example, we’re going to use TypeScript.

For more details, please see the TypeScript section in the Reference manual.

The output of the Kitten init command in terminal, showing the tasks that it accomplished: 🐱 Initialising new type-safe Kitten project in TypeScript. 🐱 Initialising npm module (npm init) 🐱 Installing TypeScript 7 as a dev dependency. 🐱 Installing @small-web/kitten-types as a dev dependency. 🐱 Creating tsconfig.json. 🐱 Creating globals.d.ts file. 🐱 Creating LICENSE file. 🐱 Creating README.md file. 🐱 Creating CHANGELOG.md file. 🐱 Creating .gitignore file. 🐱 Creating src/index.page file.
Kitten can initialise your TypeScript projects for you to save you the trouble of writing boilerplate.

Use a command like ls to see a listing of the files in your directory. This is what mine looks like:

Screenshot of directory listing showing the files Kitten has initialised the project with. They include a src folder, package.json, tsconfig.json, globals.d.ts, README.md, CHANGELOG.md, LICENSE, as well as a package-lock.json file and a node_modules folder.
Your new TypeScript project in Kitten, ready for you to start customising in the src folder.

The default behaviour of the kitten init command is to initialise a TypeScript project. You can specify that you want a JavaScript project instead by explicitly specifying it:

kitten init js

The only difference with type-safe JavaScript projects is that you have to use JSDoc to document your types.

For more details, please see the type safety section of the reference manual.

As we saw earlier, you can start playing with Kitten without any boilerplate simply by creating an empty folder and creating your first page route in JavaScript. The kitten init command, on the other hand, is there if you want to kickstart a longer-term project that you might be maintaining for months if not years. It tries to get you off to a running start by implementing good practices.

In a real-world project, the first thing you’d do after running kitten init would be to initialise your source control system. e.g., if you use git:

git init

When you do, you’ll notice that Kitten has already added a .gitignore file to your repository that lists the node_modules/ folder, the .tsbuildinfo/ folder that TypeScript writes its build information to, and those pesky .DS_Store files macOS loves to litter your directories with.

Go ahead and run Kitten and open https://localhost in your browser to see the default index page, index.page.ts, that was created in the src folder.

Screenshot of the default index page in a web browser

Before we replace the index page with our own one for this project, let’s go ahead and create the database app module so we can use it when we have our main page:

mkdir -p app_modules/database

The -p in mkdir (make directory) is the short form of the --parents flag and it instructs the command to also make any parent directories leading up to the final directory if they don’t already exist. It’s a useful shorthand so you don’t have to enter multiple mkdir commands.

Since app modules are local node modules, they must all contain a package.json file.

Create a basic package.json shell in the app_modules/database/ folder:

{
  "name": "@app/database",
  "type": "module",
  "main": "database.ts"
}

Since our database app module is a submodule of our main project, the server program in tsconfig.server.json checks it (see tsconfig.json), so we don’t have to worry about its type-safety configuration.

You could move the database app module into its own project folder but there’s really no good reason to that as it doesn’t make sense as a reusable module; it’s the database for this project and this project alone.

We do, however, have to install the JavaScript Database (JSDB) module as we will be customising the behaviour of it:

npm install @small-tech/jsdb

After you’ve installed your dependencies, your package.json file should resemble the one below:

{
  "name": "@app/database",
  "type": "module",
  "main": "database.ts",
  "dependencies": {
    "@small-tech/jsdb": "^8.0.1"
  }
}

JSDB is the database Kitten uses for databases and Kitten expects your database app modules to use it also. No other databases are supported in database app modules, although you are free to use any database under the sun in your apps via traditional methods, should you want to.

Kitten automatically installs the dependencies of app modules and checks for updated dependencies based on the package-lock.json file and installs them if necessary. As long as you make proper use of the package-lock.json file in your Small Web projects, Kitten should keep them updated for you during both development and production.

The version of JSDB in all of your package-lock.json files must match the version of JSDB in your database app module’s package.json file.

That means both the package-lock.json file of your database app module (which shouldn’t be an issue as it will be updated when you npm install JSDB) and your main package-lock.json file for the project must include the version of JSDB listed in the package.json file of your database app module.

This is easy to forget when upgrading your JSDB version as you must manually run npm install from the root folder of your project to ensure that the main project picks up the latest version in its package-lock.json file. Otherwise, Kitten’s attempt to run npm ci will fail with the following EUSAGE error:

npm ERR! `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.

Next, let’s create the database.ts file that we’ve set as the main entry point for our database app module.

  1. Since we’re using a database app module, we can persist instances of classes, so let’s create a class to represent a kitten, with a name and an age.

    export class Kitten {
      declare name: string
      declare age: number
    
      constructor ({ name, age }: {name: string, age: number }) {
        this.name = name
        this.age = age
      }
    
      toString () {
        return `${this.name} (${this.age} year${this.age === 1 ? '' : 's'} old)`
      }
    }
    

    Pay particular attention to the constructor method.

    There are two rules your custom classes must adhere to to work with JSDB:

    1. The constructor must accept a parameter object and
    2. The constructor must assign any properties it wants to persist to instance variables on itself.

    JSDB calls the constructor with a parameter object when recreating instances of persisted custom objects and any changes to the properties of instances of the class are automatically persisted by JSDB.

    Here, we are persisting the properties we care about manually. In the next step, we will see how to easily persist all passed properties.

    Notice that we override the base toString() method to display a friendly description of each kitten when it’s printed out.

  2. Next, let’s define the schema of the database.

    Alongside an array of kittens (Array<Kitten>), our database will have an object to hold metadata, which we will use to store a property that flags whether the database has been initialised or not. This will allow us to populate it with some sample kittens on the first run.

    First, let’s create the simple metadata class:

    class Metadata {
      declare initialised: boolean
    
      constructor (parameters = {}) {
        Object.assign(this, parameters)
        this.initialised ??= false
      }
    }
    

    And then the database schema interface:

      interface DatabaseSchema {
        meta: Metadata
        kittens: Array<Kitten>
      }
    

    In the Metadata class, notice how we’re using Object.assign() to copy all the properties in the parameter object into our instance. This is a useful shorthand.

    Unless you declare the properties you care about as instance variables, as we did here with declare initialised: boolean, you won’t get type safety for them when using the Object.assign() method. If you want to assign default values for them, you should do so conditionally, after you persist any passed properties, as we’re doing here.

  3. Let’s refactor the Kitten class to also use this idiom:

    export class Kitten {
      declare name: string
      declare age: number
    
      constructor (parameters = {}) {
        Object.assign(this, parameters)
      }
    
      toString () {
        return `${this.name} (${this.age} year${this.age === 1 ? '' : 's'} old)`
      }
     }
    

    If you need to access the database itself from inside your model classes, you cannot do so in the constructor or in regular instance properties (because the database will not have been initialised yet when your object is being initialised as part of the database initialisation).

    Instead, you can do so in regular methods and, if you want to assign values from the database to properties of your class, you can use accessors as these are not evaluated at instance creation but lazily when called during the execution of your app (by which time the database will, of course, have been initialised). However, note the caveat below:

    While get methods are safe to use, do not use setter methods (the set accessor) in your custom classes as they may not behave as you expect. Instead of set something () { … } use setSomething () { … } for more predictable behaviour.

    Other than that, you can do anything you can do with a regular class, like extend a base class like EventEmitter, for example.

    See the Custom data types section of the JSDB documentation for more details.

    Our code now has less repetition in the constructor, but we have now introduced some new redundancy into our code.

    Notice the repeated Object.assign() call in the constructor in the Metadata class from before:

    class Metadata {
      declare initialised: boolean
    
      constructor (parameters = {}) {
        Object.assign(this, parameters)
        this.initialised ??= false
      }
    }
    

    This is pretty core functionality and it’s easy to forget or mistype that call in all our model classes, so let’s remove the redundancy and streamline our authoring flow by refactoring to pull out the common functionality into a base class.

    Let’s call our base class Model:

    class Model {
      constructor (parameters = {}) {
        Object.assign(this, parameters)
        this.initialise()
      }
    
      initialise () {}
    }
    

    Notice that we’ve added an optional hook method called initialise() that you can override to perform initialisation of default values for your persisted properties without having to override the constructor.

    Now, we can make both our Kitten and Metadata classes extend the Model class:

    class Metadata extends Model {
      declare initialised: boolean
    
      override initialise () {
        this.initialised ??= false
      }
    }
    
    export class Kitten extends Model {
      declare name: string
      declare age: number
    
      override toString () {
        return `${this.name} (${this.age} year${this.age === 1 ? '' : 's'} old)`
      }
    }
    

    Ah, that’s a bit better. It should now be easier to author model classes in the future should we need to.

    You can see a real-world implementation of the Model class, as well as another base class that extends it called Collection, in the source code for the Gaza Verified web site.

    And now for the trickiest bit, opening the JSDB database properly.

  4. To open the JSDB database, we must pass JSDB’s static open method a reference to the path that the database lives in as well as an optional options object. This options object must contain references to any the classes of any instances we’ve persisted so that JSDB can recreate them when loading the database:

    // When the database is being opened by the db commands, we don’t compact it.
    const compactOnLoad = process.env.jsdbCompactOnLoad === 'false' ? false : true
    
    // Open (or create, if it doesn’t exist yet) the database.
    export const db:DatabaseSchema = (
      JSDB.open(
        path.join(kitten.paths.APP_DATA_DIRECTORY, 'db'),
        {
          compactOnLoad, 
          classes: [
            Metadata,
            Kitten
          ]
        }
      )
    )
    
    export default db
    

    If you forget to add a class when opening your database, Kitten will crash with an error similar to the following:

    Error: 😿 Found database module but could not import and initialise it.
    …
    Error: Metadata class missing in JSDB.open()
    

    We set JSDB’s compactOnLoad option based on the value of the process.env.jsdbCompactOnLoad environment variable set by Kitten. This is to enable Kitten’s database commands to run without compacting (and thereby altering) your database tables while your app might be running (e.g., when you’re debugging your app by running the kitten db tail command in a separate Terminal window/pane).

  5. Finally, we can export an initialise() method that will be called by Kitten to carry out database initialisation:

    export async function initialise () {
      if (!db.meta) {
        db.meta = new Metadata() 
      }
    
      if (!db.meta.initialised) {
        db.kittens = [
          new Kitten({name: 'Sushi', age: 1}),
          new Kitten({name: 'Ms. Meow', age: 3}),
          new Kitten({name: 'Whiskers', age: 7})
        ]
        db.meta.initialised = true
        console.info(`\n  • Database initialised.`)
      }
    
      return db
    }
    

    Kitten imports and runs the initialise() method before starting the server when a database app module is found in your project. Furthermore, it takes the database reference returned from this function and sets it as the default database (globalThis.kitten.db or, simply, kitten.db).

    Even though we are not making use of it here, the initialise method can take a parameter object. This object has an internalClasses object that contains a reference to useful internal classes. Currently, there is only one class listed, Upload, that you should include in your list of classes when opening the JSDB database if your app stores instances of the Upload class passed to your routes in the request.uploads array.

    So your initialise method is actually called like this by Kitten:

      initialise({
        internalClasses: {
          Upload
        }
      })
    

So, when we put that all together, we get our database app module, which looks like this:

import path from 'node:path'
import JSDB from '@small-tech/jsdb'

class Model {
  constructor (parameters = {}) {
    Object.assign(this, parameters)
    this.initialise()
  }

  initialise () {}
}

export class Kitten extends Model {
  declare name: string
  declare age: number

  override toString () {
    return `${this.name} (${this.age} year${this.age === 1 ? '' : 's'} old)`
  }
}

interface DatabaseSchema {
  meta: Metadata
  kittens: Array<Kitten>
}

class Metadata extends Model {
  declare initialised: boolean

  override initialise () {
    this.initialised ??= false
  }
}

// When the database is being opened by the db commands, we don’t compact it.
const compactOnLoad = process.env.jsdbCompactOnLoad === 'false' ? false : true

// Open (or create, if it doesn’t exist yet) the database.
export const db:DatabaseSchema = (
  JSDB.open(
    path.join(kitten.paths.APP_DATA_DIRECTORY, 'db'),
    {
      compactOnLoad, 
      classes: [
        Metadata,
        Kitten
      ]
    }
  )
)

export async function initialise () {
  if (!db.meta) {
    db.meta = new Metadata() 
  }

  if (!db.meta.initialised) {
    db.kittens = [
      new Kitten({name: 'Sushi', age: 1}),
      new Kitten({name: 'Ms. Meow', age: 3}),
      new Kitten({name: 'Whiskers', age: 7})
    ]
    db.meta.initialised = true
    console.info(`\n  • Database initialised.`)
  }

  return db
}

export default db

If something isn’t working a good first place to start is to run the TypeScript type checker. Your editor likely already does this but Kitten adds a typecheck script to the package.json file when it initialises a project.

You can run it using:

npm run typecheck

If you look in the package.json file, you’ll see that the typecheck script simply runs npx tsc -b. (Kitten also installs TypeScript 7 as a devDependency of your module.)

So our database app module is ready so now comes the fun part: using it.

First, let’s actually install the database app module as a dependency of our project.

From the main project folder, run:

npm install ./app_modules/database

That will install the database app module as a dependency, so you can refer to it as @app/database in your imports, and add an entry in your project’s package.json file that looks like this:

"dependencies": {
  "@app/database": "file:app_modules/database",
  …
}

Finally, let’s replace the index page under src/index.page.ts so that we display the names and ages of the kittens in our database:

import { db } from '@app/database'

export default function () {
  return kitten.html`
    <h1>Kittens</h1>

    <ul>
      ${db.kittens.map(currentKitten => kitten.html`
        <li>${currentKitten}</li>
      `)}
    </ul>
  `
}

Using database app modules your database, like the rest of your project, can be strongly typed.

And, more importantly, you can store and retrieve instances of JavaScript classes.

View the type of the currentKitten variable in the html template, for example, to confirm that it is, indeed, a Kitten instance.

Also note that because the kittens are instances of the Kitten class, we can simply refer to them in the template and their description will be printed out for us as their overridden toString() methods are called behind the scenes.

Phew! So that was a lot. But I hope you now have some idea of some of the cool things you can achieve using JSDB in your Small Web apps.

Now, let’s take a look at how you can work with remote APIs and, as we foray into dealing with untrusted data, at how Kitten automatically handles sanitisation and what options you have for either overriding or manually triggering sanitisation.

Next tutorial: Fetching and working with data

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.