Core utilities

This page lists the main features and utilities you can find in the core/ folder. They are used throughout the website so it might be worth taking a moment to learn what's at your disposal.

Cache

File: cache.ts

We use node-cache as a simple in-memory cache to avoid unnecessary database spam. We mostly use them at the service-level to store information that rarely changes (global settings, events, etc.).

Caching database results is very effective to gain performance, but also very fragile as data can become outdated. Because of this, cache invalidation must be carefully thought of for every use.

Constants & enums

Files: core/constants.ts, core/enums.ts

A simple set of hardcoded constants. Not to be confused with "config" (the configuration of the server as set in config.js) and "settings" (live configuration stored in the database, can be edited online by administrators)

The enums are mostly useful when you manipulate Events: the contain all the possible values for the various state fields, like whether theme voting is pending, open, in shortlist mode, or closed, etc.

DB & Models

Files: core/db.ts, core/models.ts

You will mostly manipulate the database through the models, with for instance await models.Event.fetchAll(). While the models API is effective, it also has its limitations. For advance uses, performance-sensitive queries, or situations where a full ORM is overkill, you might prefer to access the full Bookshelf and Knex API by importing db.ts instead. Example:

let platformNames = await db.knex('platform').select('name') // "platformNames" will be an array of string

File storage

File: core/file-storage.ts

This is the API used to you manage all file operations, and pictures uploads in particular. It supports picture resizing, thumbnail generation etc. thanks to the Sharp library.

Forms

File: core/forms.ts

Every data gathered from user input (forms, but also query parameters) must be verified and sanitized with the help of the forms utils. This file is also where we implement Markdown support.

Log

File: core/log.ts

Logging utilities using Winston.

Middleware

File: core/middleware.ts

This technical file is not a library of tools, but rather a followup of the server.ts boot code. This is where the Express web framework is being configured:

• Express extensions (like Promises support, form data parsing, CSRF prevention and user sessions)
• Nunjucks templating, including custom globals and filters
• Error handling