helpers

introduction

dframework exposes a set of global helper functions available in every controller, middleware, model, view, and job without requiring any imports. these helpers cover type checking, data manipulation, url generation, response shortcuts, validation, translation, and facade access to core services.

all helpers are registered on the global scope when the application initializes.

type checks

1isString('hello');     // true
2isNumber(42);          // true
3isNumber(NaN);         // false
4isObject({ a: 1 });    // true
5isObject([1, 2]);      // false
6isObject(null);        // false

value checks

isEmpty(value)

returns true if the value is considered empty. the following are considered empty: undefined, null, empty string '', empty array [], and empty plain object {}.

1isEmpty('');           // true
2isEmpty([]);           // true
3isEmpty({});           // true
4isEmpty(null);         // true
5isEmpty(0);            // false
6isEmpty('hello');      // false
7isEmpty([1]);          // false

string and array utilities

these helpers work polymorphically on both strings and arrays.

move(input, from, to)

moves an element from one index to another within a string or array. returns a new value without mutating the original.

1move([1, 2, 3, 4], 0, 2);   // [2, 3, 1, 4]
2move('abcd', 0, 2);          // "bcad"

remove(input, index)

removes the element at the specified index from a string or array.

1remove([1, 2, 3], 1);        // [1, 3]
2remove('hello', 1);           // "hllo"

replace(input, index, newItem)

replaces the element at the specified index with a new value.

1replace([1, 2, 3], 1, 9);    // [1, 9, 3]
2replace('hello', 0, 'H');    // "Hello"

limit(input, maxLength)

truncates a string or array to the specified maximum length.

1limit('hello world', 5);     // "hello"
2limit([1, 2, 3, 4, 5], 3);  // [1, 2, 3]

uniquify(input)

removes duplicate values from a string (by character) or array.

1uniquify([1, 2, 2, 3, 3]);  // [1, 2, 3]
2uniquify('aabbcc');           // "abc"

random and time

random(min, max)

generates a random integer between min and max (inclusive).

1random(1, 10);   // e.g. 7
2random(0, 1);    // 0 or 1

now()

returns the current date and time as an iso 8601 string.

1now();   // "2026-06-05T02:30:00.000Z"

html and security

escapeHtml(value)

escapes html special characters to prevent xss attacks. escapes ", &, ', <, and >. returns an empty string for null and undefined.

1escapeHtml('<script>alert("xss")</script>');
2// "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
3 
4escapeHtml(null);   // ""

this function uses a single pass algorithm on large strings. the view engine's {{ }} syntax calls this function automatically.

escapeJs(value)

escapes characters for safe usage inside javascript string literals and template strings. escapes \, ', ", `, $, control characters (newlines, carriage returns, tabs, null bytes, backspaces, form feeds), / (to prevent </script> tag breakout), and unicode line/paragraph separators (\u2028 and \u2029). returns an empty string for null and undefined.

1escapeJs('hello "world", it\'s `cool` </script>');
2// "hello \\\"world\\\", it\\\'s \\\`cool\\\` <\\/script>"
3 
4escapeJs(null);   // ""

emptyImage()

returns a data uri for a transparent 1x1 gif image. useful as a placeholder src attribute.

1emptyImage();
2// "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs="

array helpers

arrayFirst(arr, callback)

returns the first array element that satisfies the callback function. returns undefined if no element matches.

1arrayFirst([1, 2, 3, 4], n => n > 2);   // 3

arrayLast(arr, callback)

returns the last array element that satisfies the callback function.

1arrayLast([1, 2, 3, 4], n => n < 4);    // 3

pluck(arr, key)

extracts a single property from each object in an array.

1pluck([{ name: 'tarou' }, { name: 'satou' }], 'name');
2// ['tarou', 'satou']

merge(...args)

deep merges multiple objects or arrays. arrays are concatenated. objects are recursively merged, with later values overriding earlier ones for conflicting keys.

1merge({ a: 1 }, { b: 2 });                    // { a: 1, b: 2 }
2merge({ a: { x: 1 } }, { a: { y: 2 } });      // { a: { x: 1, y: 2 } }
3merge([1, 2], [3, 4]);                        // [1, 2, 3, 4]

object helpers

old(key, fallback)

retrieves flashed old input from the previous request. this is useful for repopulating form fields after a validation failure.

1old('email');                    // the previously submitted email value
2old('name', 'default name');     // returns 'default name' if no old input exists

deep object access

these helpers provide safe access to deeply nested object properties using dot notation.

get(obj, path, defaultValue)

retrieves a nested value using a dot separated key path. returns defaultValue if the path does not exist.

1const config = { database: { host: 'localhost', port: 3306 } };
2 
3get(config, 'database.host');              // 'localhost'
4get(config, 'database.name', 'mydb');      // 'mydb'
5get(config, 'missing.key');                // undefined

set(obj, path, value)

sets a nested value using a dot separated key path. creates intermediate objects as needed. mutates and returns the original object.

1const config = {};
2set(config, 'database.host', 'localhost');
3// { database: { host: 'localhost' } }

has(obj, path)

returns true if the dot separated path exists in the object.

1has({ a: { b: 1 } }, 'a.b');    // true
2has({ a: { b: 1 } }, 'a.c');    // false

forget(obj, path)

deletes a nested property by dot separated path. if the parent is an array, the element is spliced out. mutates and returns the original object.

1const data = { user: { name: 'satou', age: 30 } };
2forget(data, 'user.age');
3// { user: { name: 'satou' } }

url and asset helpers

asset(path)

generates a url for a static asset in the public directory. strips leading slashes and prepends a single /.

1asset('css/app.css');     // '/css/app.css'
2asset('/js/main.js');     // '/js/main.js'

storage(path)

generates a url for a file in the storage directory. prepends /storage/.

1storage('avatars/user-1.jpg');     // '/storage/avatars/user-1.jpg'
2storage(null);                     // ''

url(path, params)

generates a url with parameter substitution. replaces :param placeholders with the corresponding values from the params object. values are url encoded.

1url('/users/:id', { id: 42 });
2// '/users/42'
3 
4url('/posts/:slug/comments/:commentId', { slug: 'hello-world', commentId: 7 });
5// '/posts/hello-world/comments/7'

localization and ruby helpers

t(req, key, params?, fallback?)

retrieves a localized string for the specified key from the lang/{locale}/ json files. supports :name variable substitution and inline 漢字[かんじ] furigana parsing.

1await t(req, 'messages.greeting', { name: '太郎' });
2// "こんにちは、太郎さん！"
3 
4await t(req, 'messages.welcome', { name: '山田' });
5// "<ruby>東京<rt>とうきょう</rt></ruby>へようこそ、山田さん！"

ruby(baseOrText, reading?)

generates html <ruby>base<rt>rt</rt></ruby> annotations for japanese furigana text. accepts either two arguments (kanji and reading) or a single string containing inline 漢字[かんじ] annotations.

1ruby('漢字', 'かんじ');
2// "<ruby>漢字<rt>かんじ</rt></ruby>"
3 
4ruby('日本[にほん]語[ご]');
5// "<ruby>日本<rt>にほん</rt></ruby><ruby>語<rt>ご</rt></ruby>"

response helpers

these helpers are shortcuts for calling methods on the current request context's response object.

1export default class HomeController {
2  async index() {
3    return render('home', { title: 'welcome' });
4  }
5 
6  async store(req) {
7    await Item.create(req.body);
8    return redirect('/items');
9  }
10 
11  async api(req) {
12    const items = await Item.all();
13    return json({ items });
14  }
15}

routing helpers

route(name, params)

generates a url from a named route. substitutes :param placeholders with values from the params object. for domain bound routes, returns a protocol relative absolute url (such as //admin.example.com/dashboard) with domain parameter substitution.

1route('users.show', { id: 42 });
2// '/users/42'
3 
4route('admin.dashboard');
5// '//admin.example.com/dashboard'

the Route facade must be initialized before using this helper. it is automatically available in all request contexts.

routeIs(name, params?)

checks if the current request's route matches the given name. supports wildcard patterns with *. accepts an optional params object to constrain the match to specific route parameters.

1routeIs('dashboard');       // exact match
2routeIs('admin.*');         // matches admin.users, admin.settings, etc.
3 
4// constrain to a specific document page
5routeIs('docs.render', { slug: 'getting-started', page: 'installation' });

when params are supplied, each key must exactly match (string comparison) the corresponding value on req.params. use this inside view templates to determine which navigation link is active for parameterized routes.

validation

validate(dataOrReq, rules, messages)

validates data against a set of rules. accepts either a plain object or a request object (from which body and files are extracted).

1const v = validate(req, {
2  email: 'required|email',
3  password: 'required|string|min:8',
4  age: 'nullable|integer|min:18'
5});
6 
7if (v.fails()) {
8  return json({ errors: v.errors() });
9}

the validation result provides the following methods:

available rules

file validation rules

1const v = validate(req, {
2  avatar: 'file_required|file_size:5mb|file_mimes:jpg,png,webp',
3  documents: 'file|file_max_count:10|file_size:20mb'
4});

custom error messages

you can override the default error messages by passing a messages object keyed by field.rule.

1const v = validate(req, {
2  email: 'required|email'
3}, {
4  'email.required': 'please enter your email address',
5  'email.email': 'the email format is invalid'
6});

data sanitization

sanitizeBody(data, fields)

sanitizes and casts raw input data based on field type definitions. this is useful for ensuring form data is cast to the correct types before processing.

1const cleaned = sanitizeBody(req.body, [
2  { name: 'age', type: 'integer' },
3  { name: 'score', type: 'number' },
4  { name: 'active', type: 'boolean' },
5  { name: 'tags', type: 'array' },
6  { name: 'metadata', type: 'json' }
7]);

fields with null or undefined values are omitted from the result.

translation

t(req, key, fallback)

retrieves a translated string for the current locale. see the localization documentation for full details.

1const welcome = await t(req, 'common.welcome');
2const missing = await t(req, 'common.unknown', 'fallback text');

facades

dframework provides global facades for core services. these facades are available in the global scope and resolve to the current application instance's service.

session

the Session facade provides access to the current request's session store.

1await Session.set('theme', 'dark');
2const theme = await Session.get('theme', 'light');
3await Session.flash('status', 'saved successfully');

auth

the Auth facade provides access to authenticated users, guards, and authentication actions.

1if (Auth.check()) {
2  const user = Auth.user();
3  const userId = Auth.id();
4}
5 
6// using guards
7if (Auth.guard('admin').check()) {
8  const admin = Auth.guard('admin').user();
9}
10 
11await Auth.login(user, { role: 'admin' });
12await Auth.guard('admin').login(adminUser);
13 
14// log out of default guard only
15await Auth.logout();
16 
17// log out of admin guard only
18await Auth.guard('admin').logout();
19 
20// flush all guards and sessions
21await Auth.flush();

Auth.login() and Auth.guard().login() accept an optional third argument. when set to true, the session uses a long-lived cookie instead of a browser session cookie.

db

the DB facade provides direct access to the database instance. it delegates all calls to the application's database connection.

1const users = await DB.table('users').where('active', true).get();
2const count = await DB.table('orders').count();
3await DB.raw('SELECT * FROM users WHERE id = ?', [1]);

job

the Job facade dispatches background jobs to the worker pool. see the jobs and queues documentation for full details.

1Job.dispatch('SendEmailJob', { to: 'user@example.com', template: 'welcome' });

log

the Log facade provides global access to the application logger. see the logging and errors documentation for full details.

1Log.debug('processing started');
2Log.info('user registered:', user.email);
3Log.warn('rate limit approaching');
4Log.error('payment failed:', err);
5Log.table(rows, 'query results');