Understanding Gingee Scripts

Gingee executes your backend logic using JavaScript files that live inside your app's secure box folder. For consistency and ease of use, all executable scripts—whether they are handling a live API request, acting as middleware, or performing a one-time setup task—share the same fundamental structure. This guide explains the three types of scripts and the powerful $g object that connects them.

The Consistent Script Pattern

All Gingee scripts, regardless of their purpose, follow this simple and mandatory pattern:

// A script must export a single asynchronous function.
module.exports = async function() {

    // The entire logic is wrapped in a call to the global 'gingee()' function.
    await gingee(async function($g) {

        // Your application code goes here.
        // You use the '$g' object to interact with the world.
        
    });
};

This unified structure ensures that every piece of executable code runs within the same secure, sandboxed environment and receives a properly configured context object ($g).

Types of Scripts in Gingee

While the structure is the same, the purpose of a script and the context it runs in can differ. There are three types of scripts you can create.

1. Server Scripts (API Endpoints)

This is the most common type of script. It runs in direct response to an incoming HTTP request from a browser or client.

Example (box/api/users/get.js):

module.exports = async function() {
    await gingee(async ($g) => {
        const userId = $g.request.query.id;
        // ... logic to fetch user from database ...
        $g.response.send({ id: userId, name: 'Alex' });
    });
};

2. Default Include Scripts (Middleware)

These scripts run before every Server Script in your application. They act as middleware.

Example (box/auth_middleware.js):

module.exports = async function() {
    await gingee(async ($g) => {
        const token = $g.request.headers['x-auth-token'];
        if (!isValid(token)) {
            // This ends the request immediately.
            $g.response.send({ error: 'Unauthorized' }, 401);
        }
        // If we don't send a response, execution continues to the next script.
    });
};

3. Startup Scripts (Initialization)

These scripts run once when your application is loaded by the server. They are not tied to any HTTP request.

Example (box/setup/create_schema.js):

module.exports = async function() {
    await gingee(async ($g) => {
        const db = require('db');
        $g.log.info('Checking for Users table...');
        
        const sql = 'CREATE TABLE IF NOT EXISTS "Users" (id SERIAL PRIMARY KEY, email TEXT)';
        await db.execute('main_db', sql);
        
        $g.log.info('Database schema is ready.');
    });
};

The $g Object: Full API Reference

The $g object is the heart of the server script API. It provides a simplified and secure facade for interacting with the HTTP request, building a response, logging, and accessing application configuration.

$g.request

An object containing all the details of the incoming HTTP request.

$g.response

An object used to build the outgoing HTTP response. You modify its properties and then call $g.response.send() to send it.

$g.log

A direct reference to the apps's logger instance, pre-configured with the request's context.

$g.app

An object containing safe, read-only configuration data for the current application.

NOTE: The $g object will not have the $g.request and $g.response objects for a startup script.