Index › 9. Database App Modules
See how to implement type safety for your databases by creating and using database app modules.
Topics covered
- Kitten’s design philosophy of beautiful defaults and layered complexity.
- Persisting custom objects (instances of your custom classes).
- App Modules.
- Database App Modules.
- How Kitten handles Node module dependencies (automatic updates using
npm ci, etc.) - Database compaction.
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.

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

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.

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.
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
constructormethod.There are two rules your custom classes must adhere to to work with JSDB:
- The constructor must accept a parameter object and
- 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.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
Metadataclass, notice how we’re usingObject.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 theObject.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.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
getmethods are safe to use, do not use setter methods (thesetaccessor) in your custom classes as they may not behave as you expect. Instead ofset something () { … }usesetSomething () { … }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 theMetadataclass 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
KittenandMetadataclasses extend theModelclass: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
Modelclass, as well as another base class that extends it calledCollection, in the source code for the Gaza Verified web site.And now for the trickiest bit, opening the JSDB database properly.
To open the JSDB database, we must pass JSDB’s static
openmethod 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 dbIf 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
compactOnLoadoption based on the value of theprocess.env.jsdbCompactOnLoadenvironment 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 thekitten db tailcommand in a separate Terminal window/pane).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.dbor, simply,kitten.db).Even though we are not making use of it here, the
initialisemethod can take a parameter object. This object has aninternalClassesobject that contains a reference to useful internal classes. Currently, there is only one class listed,Upload, that you should include in your list ofclasseswhen opening the JSDB database if your app stores instances of theUploadclass passed to your routes in therequest.uploadsarray.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