Embedded JavaScript runtime modules

[tobiemh]

Extending the embedded JavaScript runtime with in-built and custom modules will allow SurrealDB users to implement advanced logic and functionality within SurrealDB. This could include custom logic, implementing specific business logic, making payments, and calling external APIs.

In-built modules

The most important built-in module is one that allows the user to query the current database instance, using the current scope and authentication. This would be similar to how the surrealdb.js library works, without the connection functionality, and without the ability to switch namespace / database, or change authentication levels.

import { query } from "surrealdb";

let users = query('SELECT * FROM user WHERE age > $age', {
    age: 18,
});

SurrealDB SQL functions could be made available within JavaScript too.

import { functions } from "surrealdb";

let area = functions.geo.area({
    type: "Polygon",
    coordinates: [[
        [-0.38314819, 51.37692386], [0.1785278, 51.37692386],
        [0.1785278, 51.61460570], [-0.38314819, 51.61460570],
        [-0.38314819, 51.37692386]
    ]]
});

Another module which should be built-in as a global is the fetch command;

/**
 * Output: JSON Data
 */
const jsonResponse = await fetch("https://api.github.com/users/denoland");
const jsonData = await jsonResponse.json();
console.log(jsonData);

/**
 * Output: HTML Data
 */
const textResponse = await fetch("https://deno.land/");
const textData = await textResponse.text();
console.log(textData);

/**
 * Output: Error Message
 */
try {
  await fetch("https://does.not.exist/");
} catch (error) {
  console.log(error);
}

Third-party modules

Local modules

Local modules could be imported directly with an ES6 import declaration. We would need to decide how local modules are defined (using a custom DEFINE statement with the JavaScript / TypeScript code).

import { add, multiply } from "mymodule";

Remote modules

Remote modules could be imported directly with an ES6 import declaration. Remote modules would need to be cached, and if we support TypeScript then we would need to convert this to JavaScript on the fly, and cache the result.

import { add, multiply } from "https://x.nest.land/[email protected]/source/index.js";

[ansarizafar]

Instead of embedded modules and endpoints, I suggest stored procedure/functions with public or private modifiers. Public procedures/functions can also have access permission. We can define a function with Define Function

Define Function <function_name> Arguments <arguments> Public | Private Permissions <permissions>

We should be able to execute these procedures with Execute statement

Execute <function_name> Arguments

Surrealdb admin GUI should also has a built-in code editor for writing these functions.

[tobiemh]

@ansarizafar based on your suggestion, what language do you see the stored procedure/function being written in?

Could you give a complete example of defining a stored procedure (including the function code/statements themselves), so that I can get a better understanding?

[ansarizafar]

SurrealDB is already using quickjs so can we can use javascript for writing these procedures.

I was in favor of embedded endpoints previously https://discord.com/channels/902568124350599239/902568124350599242/977836523863019530 but now I think there are few advantages of using stored procedures. SQL developers are already familiar with stored procedures, embedded endpoints in a database is a new concept for them (only Arangodb allows writing endpoints with javascript) and we can define and execute stored procedures with SQL statements. No need to expose HTTP endpoints and access these URLs from client.

Here is stored procedures purposed syntax

// Private/Internal procedures can be called from other procedures but not accessible from client. 
// Global Surreal object should be available inside procudure/function body.

DEFINE PROCEDURE <proc_name>(arg1, arg2,...) Public | Private PERMISSIONS where $auth.admin = true 
{

// Javascript code

return some_value
}

// Execute syntax

EXECUTE <proc_name>(arq1, arg2, ...)

[tobiemh]

What would be the purpose of Public or Private if a PERMISSIONS clause is defined?

[ansarizafar]

As I mentioned in earlier comment Private/Internal procedures/methods can be called from other procedures but not directly accessible from client. Private methods are for reusable code only.

REST Endpoints have one advantage, They can be used as hooks.