Global - Backendjs Documentation

Type Definitions

ConfigOptions

Config parameters defined in a module as a list of objects.

Properties:

Name	Type	Attributes	Description
`name`	string		parameter name, can be a string regexp to match dynamic parameters, matched pieces then can be used by the `make` property to build the final variable name.
`descr`	string		parameter description, it is show when run `bksh -help` command
`type`	string	<optional>	a valid config type: none - skip this parameter bool - converts to a boolean int, real, number - converts to a number map - convert `key:value,key:value...` pairs into an object, see delimiter/separator properties set, list - array type, set makes the list unique, splits strings by separator or `,\|` regexp - a RegExp regexpobj - add a regexp to the object that consist of list of patterns and compiled regexp, lib.testRegexpObj regexpmap - Add a regexp to the list of regexp objects url - an object produces by URL.parse json, js - parse as JSON into an object/array path - resolves to an absolute path callback - calls the callback property only, does not save file - reads contents of the file
`obj`	string	<optional>	object name in the module where to store the value, otherwise the value is defined in the module, the obj name is stripped automatically from the variable name. The object name can contain dots to point to deep objects inside the module.
`make`	string	<optional>	make the variable name from the matched pieces, the final variable is constructed by replacing every `$1`, `$2`, ... with corresponding matched piece from the name regexp.
`array`	boolean	<optional>	if true prepend a value to the list, to remove an item prepend it with `!!`
`push`	boolean	<optional>	for array: mode append a value
`pass`	int	<optional>	process only args that match the pass value
`env`	string	<optional>	env variable name to apply before parsing config files
`merge`	boolean	<optional>	if true merge properties with existing object, 'obj' must be provided
`maptype`	string	<optional>	default is `auto` to parse map values or can be any value type, for type `map`
`make`	string	<optional>	works with regexp names like `name-([a-z]+)-(.+)` to build the final parameter name, can use $1, $2, $3...placeholders
`novalue`	string \| Array.<string>	<optional>	skip if value is equal or included in the list, also works for merges
`sort`	boolean	<optional>	sort array params
`unique`	boolean	<optional>	only keep unique items in lists
`camel`	string	<optional>	characters to use when camelizing the name, default is "-"
`nocamel`	boolean	<optional>	do not camelize the name
`noempty`	boolean	<optional>	do not save empty values
`autotype`	boolean	<optional>	detect type by using module:lib.autoType
`novalue`	string \| Array.<string>	<optional>	do not save if matches given string or contained in the list
`example`	string	<optional>	text with examples
`callback`	function	<optional>	function to call for the callback types for manully parsing and setting the value, (value, obj) the obj being current parameter
`onupdate`	function \| string	<optional>	function to call at the end for additional processing as (value, obj)
`separator`	string	<optional>	separator to use for `list` and `map` items, for lists default is `,\|`, for maps it is `:;`
`delimiter`	string	<optional>	separator to split key:value pairs, default is `,`
`empty`	boolean	<optional>	allows empty values for maps and regexps
`ephemeral`	boolean	<optional>	parsed but not saved, usually it is handled by onupdate callback
`strip`	string	<optional>	text to stripo from the final variable name
`once`	boolean	<optional>	only set this parameter once

Type:

object

DBConfigOptions

Common options for the pools that customize behaviour

Properties:

Name	Type	Description
`upgrade`	boolean	perform alter table instead of create
`typesMap`	boolean	type mapping, convert lowercase type into other type supported by any specific database
`noDefaults`	boolean	ignore default value if not supported (Cassandra)
`noNulls`	boolean	NOT NULL restriction is not supported (Cassandra)
`noMultiSQL`	boolean	return as a list, the driver does not support multiple SQL commands
`noLengths`	boolean	ignore column length for columns (Cassandra)
`noIfExists`	boolean	do not support IF EXISTS on table or indexes
`noCompositeIndex`	boolean	does not support composite indexes (Cassandra)
`noAuto`	boolean	no support for auto increment columns
`skipNull`	boolean	object with operations which dont support null(empty) values

DBRequest

Properties:

Name	Type	Attributes	Description
`pool`	DbPool		a DB pool to use
`config`	DBConfigOptions		link pool.configOptions for quick convenient access
`table`	string	<optional>	a DB table name
`op`	string	<optional>	DB operation, one of get, put, incr, update, select, ...
`text`	string	<optional>	native DB query, SQL or etc...
`values`	Array.<any>	<optional>	values to be used for SQL binding
`query`	object		a query object
`options`	object \| DBRequestOptions		an object with optional properties for the operation
`keys`	Array.<string>		a list of table primary keys
`custom`	object		an object for custom columns
`columns`	object		an object with table's columns
`column`	function		returns a column object by name
`now`	int		timestamp when this is created, ms
`callback`	DBResultCallback	<optional>	callback to call after finished

Type:

object

DBRequestColumn

A column prepared to be used in conditions, see module:db.prepareColumn

Properties:

Name	Type	Attributes	Description
`name`	string		actual column name
`type`	string		type from DBTableColumn
`op`	string		operator to use in comparison or update, lowercase and all underscores are converted into spaces
`value`	any		value passed for compare or update
`join`	string		join operator, AND is default
`alias`	string		original name in case name contained _$ placeholder
`col`	DBTableColumn	<optional>	existing column definition or undefined

DBRequestOptions

Properties:

Name Type Description

options

object

may have the following properties:

Properties

Name	Type	Description
`pool`	string	name of the database pool where to execute this query. The difference with the high level functions that take a table name as their firt argument, this function must use pool explicitely if it is different from the default. Other functions can resolve the pool by table name if some tables are assigned to any specific pool by configuration parameters `db-pool-tables`.
`filterrows`	function	function to filter rows not to be included in the result, returns a new result set, args are: function(req, rows)
`processrows`	function	function to process rows in the result, returns a new result, args are: function(req, rows), this result will be put in cache if requested so this may be used for preparing cached results, it must return an array
`processasync`	function	function to process result rows via async callback, return a new result in the callback, the function is: function(req, rows, callback), the callback is function(err, rows)
`syncMode`	boolean	skip columns preprocessing and dynamic values for pool sync and backup restore
`logger_db`	string	log results at the end with this level or `debug` by default
`logger_error`	string	log errors with this level instead of `error`
`ignore_error`	boolean \| Array.<string>	clear errors occurred as it never happen, do not report in the log, if an array then only matched codes will be cleared
`noprocessrows`	boolean	if true then skip post processing result rows, return the data as is, this will result in returning combined columns as it is
`noconvertrows`	boolean	if true skip converting the data from the database format into Javascript data types, it uses column definitions
`nopreparequery`	boolean	if true skip query preparation and columns processing, the req.query is passed as is, useful for syncing between pools for the table to convert values returned from the db into the the format defined by the column
`total`	boolean	if true then it is supposed to return only one record with property `count`, skip all post processing and convertion
`info_query`	boolean	to return the record just processed in the info object as `query` property, it will include all generated and updated columns
`result_query`	boolean	to return the query record as result including all post processing and new generated columns, this is not what `returning` property does, it only returns the query record with new columns from memory
`cached`	boolean	if true then run getCached version directly
`nocache`	boolean	disable caching even if configured for the table
`ops`	object	operators to use for comparison for properties, an object with column name and operator. Common operators are, some databases may support other specific ops: between, match, regexp, iregexp, begins_with, not_begins_with, ends_with, not_ends_with, like, like%, ilike%, contains, not_contains```
`opsMap`	object	operator mapping between supplied operators and actual operators supported by the db
`typesMap`	object	type mapping between supplied and actual column types, an object
`select`	Array.<string>	a list of columns or expressions to return or all columns if not specified, only existing columns will be returned
`start`	string \| object	start records with this primary key, this is the next_token passed by the previous query
`count`	int	how many records to return
`first`	boolean	a convenient option to return the first record from the result or null (similar to `db.get` method)
`last`	boolean	similar to first but return last record
`join`	string	how to join condition expressions, default is AND
`joinOps`	object	operators to use to combine several expressions in case when an array of values is given, supports `and\|or\|AND\|OR``
`sort`	string	sort by this column. if null then no sorting must be done at all, records will be returned in the order they are kept in the DB. NOTE: For DynamoDB this may affect the results if columns requsted are not projected in the index, with sort `select` property might be used to get all required properties. For Elasticsearch if sort is null then scrolling scan will be used, if no `timeout` or `scroll` are given the default is 1m.
`sort_timeout`	int	for pagination how long to keep internal state in millisecons, depends on the DB, for example for Elasticsearch it corresponds to the scroll param and defaults to 60000 (1m)
`desc`	boolean	if sorting, do in descending order
`page`	int	starting page number for pagination, uses count to find actual record to start, for SQL databases mostly
`unique`	boolean	specified the column name to be used in determining unique records, if for some reasons there are multiple records in the location table for the same id only one instance will be returned
`cacheKey`	string	exlicit key for caching, return from the cache or from the DB and then cache it with this key, works the same as `get`
`cacheKeyName`	string	a name of one of the cache keys to use, it must be defined by a `db-cache-keys-table-name` parameter
`no_columns`	boolean	do not check for actual columns defined in the pool tables and add all properties from the obj, only will work for NoSQL dbs, by default all properties in the obj not described in the table definition for the given table will be ignored.
`skip_columns`	Array.<string>	ignore properties by name listed in the this array, the most use case is to skip autogeneratd columns like "now"

Type:

object

DBResultCallback(err, rows, info)

This callback is called by all DB methods

Parameters:

Name Type Description

err

Error

and error object or null i fno errors

rows

Array.<object>

a list of result rows, in case of error it is an empty list

info

object

an object with information about the last query:

Properties

Name	Type	Attributes	Description
`inserted_oid`	string	<optional>	new generated ID
`affected_rows`	int	<optional>	how many rows were affected by this operation
`next_token`	string	<optional>	next to ken to pass for pagination
`consumed_capacity`	int	<optional>	DynamoDB specific about capacity consumed

DBTable

Database table object, each property represents a column

Properties:

Name	Type	Description
`name1`	DBTableColumn	column1
`name2`	DBTableColumn	column2
`...`	DBTableColumn	more columns

Type:

object

DBTableColumn

Database column definition, all properties are optional

Properties:

Name Type Attributes Description

type

int

column type, supported types:

int, bigint, log, real, float, number - numeric types
bool, boolean - stored as boolean type
text, string - text types
date, time, timestamp - Date stored in database supported type, usually as text in SQL
mtime - timestamp in milliseconds
clock - timestamp in nanoseconds
json - stored as JSON text but converted to/from native Javascript objects
obj, object - native JSON object type
array - native JSON array type
list - store a list of primitive types, strings and/or numbers
set - a unique set of string or numbers
random - generates a random number in module:db.add/module:db.put methods, uses optional .max/.min properties
ttl - in add/put save as timestamp in the future to be expired by database (DynamoDB)
uuid, suuid, sfuuid - autogenerate the column value with UUID, optional prefix property will be prepended, { type: "uuid", prefix: "u_" }, see module:lib.uuid, module:lib.suuid, module:lib.tuuid
now - defines a column to be automatically filled with the current timestamp, { type: "now" }
counter - defines a columns that will be automatically incremented by the module:db.incr command, on creation it is set with 0
uid - defines a columns to be automatically filled with the current user id, this assumes that user object is passed in the options from the API level
uname - defines a columns to be automatically filled with the current user name, this assumes that user object is passed in the options from the API level
ttl - mark the column to be auto expired, can be set directly to time in the future or use one of: days, hours, minutes as a interval in the future

primary

int

column is part of the primary key, for composite keys the number defines the place starting with 1

unique

int

column is part of an unique key, the number defines the order if it is composite key

index

int

column is part of an index, the value is a number for the column position in the index

uniqueN

int

additonal unique indexes where N is 1..25

indexN

int

additonal indexes where N is 1..25

value

any

default value to save if not provided

dflt

any

default value to assign if not present in the record

length

int

column length (SQL)

not_null

boolean

true if should be NOT NULL (SQL)

auto

boolean

true for AUTO_INCREMENT column (SQL)

readonly

boolean

only add/put operations will use the value, incr/update will not affect the value

writeonly

boolean

only incr/update can change this value, add/put will ignore it

prefix

string

prefix to be prepended for autogenerated columns: uuid, suuid, sfuuid

separator

string

to be used as a separator in join or lists depending on the column properties

keyword

boolean

a hint to treat the value as it is in search (Elasticsearch)

foreign

object

foreign key reference (SQL)

Properties

Name	Type	Description
`table`	string	reference table name
`name`	string	reference table primary key
`ondelete`	string	action on delete, cascade, ...
`custom`	string	additional SQL statements

api

object

API access permisions

Properties

Name	Type	Description
`pub`	boolean	make a column as public, used by module:api.sendJSON in cleanup mode. this is very important property because it allows anybody to see it when used with the default API functions, i.e. anybody with valid credentials can retrieve all public columns from all other tables, and if one of the other tables is user table this may expose some personal information, so by default only a few columns are marked as public in the `bk_user` table
`priv`	boolean	an opposite for the pub property, if defined this property should never be returned to the client by the API handlers
`admin`	boolean	a generic read permission requires `options.isAdmin` when used with `api.cleanResult`
`staff`	boolean	a generic read permission requires `options.isStaff` when used with `api.cleanResult`
`internal`	boolean	if set then this property can only be updated by admin/root or with `isInternal`` property
`roles`	string \| Array.<string>	a role or a list of roles which further restrict access to a public column to only users with specified roles
`noroles`	string \| Array.<string>	a role or a list of roles which excplicitely deny access to a column for users with specified roles

convert

object

convert value on save

Properties

Name	Type	Description
`list`	boolean	on return splits the column value into an array, uses the `separator` property
`lower`	boolean	make string value lowercase
`upper`	boolean	make string value uppercase
`cap`	boolean	capitalize words
`strip`	regexp	if a regexp strip on the column value before saving
`replace`	regexp	if a regexp perform replace on the column value before saving
`trim`	boolean	strim string value of whitespace
`multiplier`	int	for numeric columns apply this multipliers before saving
`increment`	int	for numeric columns add this value before saving
`decimal`	int	for numeric columns convert into fixed number using this number of decimals
`format`	function	a function (val, req) => {} that must return new value for the given column, for custom formatting
`epoch`	boolean	for `now` type save as seconds since the Epoch, not milliseconds

check

object

validation checks

Properties

Name	Type	Description
`max`	int	ignore the column if a `text`, `json` or `obj` value is greater than specified limit, unless `trunc` is provided
`trunc`	boolean	truncate the column value, the value will be truncated before saving into the DB, uses the `max` as the limit
`maxlist`	int	max number of items in the `list`, `set` or `array` column types
`not_zero`	boolean	true if should be skipped if 0 value
`not_empty`	boolean	do not allow empty columns, if not provided it is filled with the default value
`skip_empty`	boolean	ignore the column if the value is empty, i.e. null or empty string
`fail_ifempty`	boolean	returtn an error if there is no value for the column, this is checked during record preprocessing

join

Array.<string>

a list with property names that must be joined together before performing a db operation, it will use the given record to produce a new property, empty properties will be still joined as empty strings.

custom

object

database specific instructions to apply when creating a table or column

Properties

Name	Type	Description
`sql`	string	apply for all SQL databases
`sqlite`	string	SQLite specific instructions
`pg`	string	PostgreSQL specific instructions
`dynamodb`	object	DynamoDB specific properties
`elasticsearch`	object	Elasticsearch specific properties

Type:

object

Members

(constant) mod

Description:

Default security implementation using acl/signature/session/users modules, no external dependencies.

Default security implementation using acl/signature/session/users modules, no external dependencies.

(constant) mod

Description:

ACL for access permissions. Each ACL is a list of RegExps with a name. ACLs are grouped by a role, at least one must match in order to succeed.

The public ACL exists with default list of files and endpoints to allow access without authentication.

ACL for access permissions. Each ACL is a list of RegExps with a name. ACLs are grouped by a role, at least one must match in order to succeed.

The public ACL exists with default list of files and endpoints to allow access without authentication.

(constant) mod

Description:

CSRF token format: TYPE,RANDOM_INT,EXPIRE_MS,[UID]

type`` is hfor header orc`` for cookie

Implements double cookie protection using HTTP and cookie tokens, both must be present.

In addition a token may contain the user id which must be the same as logged in user.

CSRF token format: TYPE,RANDOM_INT,EXPIRE_MS,[UID]

type`` is hfor header orc`` for cookie

Implements double cookie protection using HTTP and cookie tokens, both must be present.

In addition a token may contain the user id which must be the same as logged in user.

(constant) mod

Description:

Hook: sig

The purpose of this hook is to manage custom signatures.
- method can be '' in such case all methods will be matched
- path is a string or regexp of the request URL similr to registering Express routes
- callback is a function(req, user, sig, cb) where
  - if sig is null it means to generate a new signature for the given user and return in the callback, if multiple hooks are registered the processing stops on first signature returned
  - if sig is provided that means to verify the signature against given user and return it if valid or return null if it is invalid or cannot be verified by current hook, multiple hooks can be supported and it stops on first signature returned in the callback
Example:
```
      api.hooks.add("sig", '', '/', (req, user, sig, cb) => {
           if (sig) {
               if (invalid) sig = null;
           } else {
               sig = api.createSignature(.....);
           }
           cb(sig)
      });
```

Hook: sig

The purpose of this hook is to manage custom signatures.

method can be '' in such case all methods will be matched
path is a string or regexp of the request URL similr to registering Express routes
callback is a function(req, user, sig, cb) where
- if sig is null it means to generate a new signature for the given user and return in the callback, if multiple hooks are registered the processing stops on first signature returned
- if sig is provided that means to verify the signature against given user and return it if valid or return null if it is invalid or cannot be verified by current hook, multiple hooks can be supported and it stops on first signature returned in the callback

Example:

      api.hooks.add("sig", '', '/', (req, user, sig, cb) => {
           if (sig) {
               if (invalid) sig = null;
           } else {
               sig = api.createSignature(.....);
           }
           cb(sig)
      });

(constant) mod

Description:

Passkey management

To allow login via passkey enable

-api-passkeys-cap-enabled 1

Passkey management

To allow login via passkey enable

-api-passkeys-cap-enabled 1

(constant) mod

Description:

User management

To disable default endpoints

-api-users-cap-disabled 1

User management

To disable default endpoints

-api-users-cap-disabled 1

(constant) net

Description:

Author: Vlad Seryakov vseryakov@gmail.com backendjs 2025

Author: Vlad Seryakov vseryakov@gmail.com backendjs 2025

Methods

TokenBucket()

Description:

Create a Token Bucket object for rate limiting as per http://en.wikipedia.org/wiki/Token_bucket
- rate - the rate to refill tokens
- max - the maximum burst capacity
- interval - interval for the bucket refills, default 1000 ms
Store as an array for easier serialization into JSON when keep it in the shared cache.

Based on https://github.com/thisandagain/micron-throttle

Trace()

Description:

AWS X-Ray trace support

Only supports local daemon UDP port 2000, to test locally

socat -U -v PIPE udp-recv:2000

module:shell()

Description:

Shell command interface for bksh

Run bksh -help to see all registered shell commands.

Special command-lone arguments for shell commands:
- -noexit - keep the shell running after executing the command
- -exit - exit with error if no shell command found
- -exit-timeout MS - will be set to ms to wait before exit for async actions to finish
- -shell-delay MS - will wait before running the command to allow initialization complete