Client

Client

Base class for nodejs clients. See module:nodejs~NodeClient for extensions.

Constructor

new Client(options, logger)

Source:
Parameters:
Name Type Description
options

see HClient base class
logger

see HClient base class

Extends

Members

app :string

Source:
Inherited From:

The app name getter/setter

Type:
  • string

Methods

(async) call(endpoint, …args) → {Promise.<*>}

Source:
Inherited From:

Call a remote procedure

Returns result, if synchronous

Parameters:
Name Type Attributes Description
endpoint string

remote procedure name
args * <repeatable>

remote procedure arguments
Returns:

result, if any

Type
Promise.<*>

(async) connect() → {Promise.<void>}

Source:
Inherited From:

Explicit connect to server, optional

Lazy (re)connection is used in all of the query functions

Returns:
Type
Promise.<void>

(async) delEnv(name)

Source:
Inherited From:

Remove (undef) an env variable

Note: you may need to run restartApp() to read in the changes (re-read process.env)

Parameters:
Name Type Description
name string

(async) getEnv()

Source:
Inherited From:

Get the current env variables from server

(async) query(query, paramsopt, waitopt) → {Promise.<Array.<object>>}

Source:
Inherited From:

Run SQL query within an implicit transaction

Parameters:
Name Type Attributes Description
query string

SQL query string
params Array.<*> <optional>

Array of query parameters
wait boolean <optional>

will wait for any server side Promises to resolve
Returns:

Array of result objects

Type
Promise.<Array.<object>>

(async) restartApp()

Source:
Inherited From:

Restart the app, will re-require all the modules

(async) run(func, …args) → {Promise.<void>}

Source:
Inherited From:

Run a custom function in a server context

Note: return value will be ignored!

Example
let res = await client.run(() => {
  console.log('will be logged')
  return 42
})
// `res` will be `null`

// compare to `wait()`
res = await client.wait(() => {
  console.log('will be logged')
  return 42
})
// `res` will be `42`
Parameters:
Name Type Attributes Description
func function

function definition
args * <repeatable>

function arguments
Returns:

doesn't return anything

Type
Promise.<void>

(async) setEnv(env)

Source:
Inherited From:

Set env vars, values will be stringified and keys uppercased

Will be merged with the current env

Note: you may need to run restartApp() to read in the changes (re-read process.env)

Parameters:
Name Type Description
env Object.<string, any>

(async) stx(func, optionsopt) → {Promise.<void>}

Source:
Inherited From:

Execute code in a server-side transaction

Example
// Create a new table
client.stx(store => {
  store.system.schema.addTable('My Table')
})
// Add a table to another app
client.stx(store => {
  store.system.schema.addTable('Some Table')
}, { owner: 'username', name: 'app' })
Parameters:
Name Type Attributes Description
func function

executed function
options AppOptions <optional>

app transaction context options
Returns:
Type
Promise.<void>

(async) stxRet(func, optionsopt) → {Promise.<void>}

Source:
Inherited From:

Execute code in a server-side transaction and return result from server to client. Can be slower than stx.

Example
// Create a new table
client.stx(store => {
  store.system.schema.addTable('My Table')
})
// Add a table to another app
client.stx(store => {
  store.system.schema.addTable('Some Table')
}, { owner: 'username', name: 'app' })
Parameters:
Name Type Attributes Description
func function

executed function returning result
options AppOptions <optional>

app transaction context options
Returns:
Type
Promise.<void>

(async) terminate(codeopt, reasonopt)

Source:
Inherited From:

Terminate the websocket

Use close() instead

Parameters:
Name Type Attributes Description
code number <optional>

websocket exit code
reason string <optional>

websocket connection close reason

(async) tx(funcopt) → {Promise.<(Tx|*)>}

Source:
Inherited From:

Create transaction and optionally execute a local sync function in the transaction block context

Example
// create transaction and execute queries
// (runs locally, sends queries to server and reads in the results)
await client.tx(async (tx) => {
  const rows = await tx.query(`select * from table`)
  for (let row of rows) {
    await tx.query(`insert into table2 values ($1, $2)`, [row.col1, row.col2])
  }
  return rows
})
// the above is equivalent to:
// (runs remotely, compiles and executes in one go)
await client.wait(() => {
  const rows = hoc.sql(`select * from table`)
  for (let row of rows) {
    hoc.sql(`insert into table2 values ($1, $2)`, [row.col1, row.col2])
  }
  return rows
})
// `client.tx()` will be much slower than `client.wait()`

// create and use an explicit transaction
const tx = await client.tx()
await tx.query(`insert into table values($1, $2)`, [1, 'a'])
// ....
// you cannot hold here too long, server will kill long transactions
await tx.commit()
Parameters:
Name Type Attributes Description
func function <optional>

function to execute locally in the transaction block, optional
Returns:

transaction class or result of executing the function

Type
Promise.<(Tx|*)>

(async) user() → {Promise.<Object.<string, any>>}

Source:
Inherited From:

Get the current user object

Only username and email properties of the object are always returned. Other props are optional, (password is always hidden)

Example
{
  username: 'johndoe',
  firstname: 'John',
  lastname: 'Doe',
  email: 'jdoe@hoctail.io',
  picture: {},
  password: '********'
}
Returns:
Type
Promise.<Object.<string, any>>

(async) wait(func, …args) → {Promise.<*>}

Source:
Inherited From:

Call an async remote procedure or execute a function and wait for the result

The only way to await for async functions/procedures

Note: will open multiple transactions! (after each await/Promise)

Example
let res = await hoctail.wait(() => { return BigInt(Number.MAX_SAFE_INTEGER + 1) })
// res = 9007199254740992n
res = await hoctail.wait(async () => {
  // first transaction
  let sum = await Promise.resolve(2)
  // second transaction (after await)
  sum += await Promise.resolve(3)
  // third transaction (after another await)
  return sum
})
// res = 5
Parameters:
Name Type Attributes Description
func function | string

inline function or remote procedure name
args * <repeatable>

function or procedure arguments
Returns:

result, if any

Type
Promise.<*>