JavaScript / TypeScript

Installation

npm install @petradb/engine

Session

new Session(options?)

Crée une nouvelle instance de base de données.

Option	Type	Par défaut	Description
rowMode	'object' | 'array'	'object'	Format de ligne par défaut pour les résultats SELECT
storage	'memory' | 'persistent' | 'text'	'memory'	Backend de stockage
path	string	—	Chemin du fichier (requis pour persistent et text)
pageSize	number	4096	Taille de page en octets (persistent uniquement)

// En mémoire (par défaut)
const db = new Session();

// Stockage persistant résistant aux pannes (Node.js)
const db = new Session({ storage: 'persistent', path: './mydb' });

// Fichier texte lisible par l'homme (Node.js)
const db = new Session({ storage: 'text', path: './data.ptxt' });

Pour le stockage persistant, PetraDB détecte automatiquement s’il faut créer un nouveau fichier ou ouvrir un fichier existant.

db.close()

Libère les descripteurs de fichiers. Retourne une Promise<void>. Requis pour le stockage persistant et texte. No-op (mais toujours asynchrone) pour les bases de données en mémoire.

await db.close();

db.execute(sql, options?)

Exécute une ou plusieurs instructions SQL séparées par ;. Retourne une promesse qui se résout en un tableau de résultats.

Option	Type	Par défaut	Description
rowMode	'object' | 'array'	valeur du constructeur	Format de ligne pour cet appel

const [{ rows, fields }] = await db.execute('SELECT * FROM users');

db.prepare(sql)

Crée un prepared statement avec les placeholders de paramètres $1, $2, … Retourne un objet statement avec une méthode execute(params, options?).

const stmt = db.prepare('SELECT * FROM users WHERE id = $1');
const [{ rows }] = await stmt.execute([42]);

// Avec options
const [{ rows }] = await stmt.execute([42], { rowMode: 'array' });

db.registerFunction(name, callback)

Enregistre une fonction JavaScript native appelable depuis SQL, les déclencheurs et les procédures stockées :

db.registerFunction('my_double', (args) => args[0] * 2);

// Maintenant utilisable en SQL :
const [{ rows }] = await db.execute('SELECT my_double(21) AS val');
// rows[0].val === 42

Le callback reçoit un tableau de valeurs JavaScript (nombres, chaînes, booléens ou null) et doit retourner une valeur JavaScript.

Interfaces TypeScript

interface SessionOptions {
  rowMode?: 'object' | 'array';
  storage?: 'memory' | 'persistent' | 'text';
  path?: string;
  pageSize?: number;
}

interface ExecuteOptions {
  rowMode?: 'object' | 'array';
}

interface PreparedStatement {
  execute(params?: any[], options?: ExecuteOptions): Promise<ExecuteResult[]>
}

class Session {
  constructor(options?: SessionOptions)
  execute(sql: string, options?: ExecuteOptions): Promise<ExecuteResult[]>
  prepare(sql: string): PreparedStatement
  close(): Promise<void>
}

Types de résultats

Chaque résultat possède un champ command pour la discrimination :

// DDL
{ command: 'create table', table: string }
{ command: 'drop table', table: string }
{ command: 'create type', type: string }
{ command: 'drop type', type: string }
{ command: 'create index', index: string }
{ command: 'drop index', index: string }
{ command: 'truncate table', table: string }
{ command: 'alter table' }
{ command: 'create view', view: string }
{ command: 'drop view', view: string }
{ command: 'create sequence', sequence: string }
{ command: 'drop sequence', sequence: string }
{ command: 'create schema', schema: string }
{ command: 'create trigger', trigger: string }
{ command: 'drop trigger', trigger: string }

// PL/pgSQL
{ command: 'do' }
{ command: 'create function', function: string }
{ command: 'drop function', function: string }
{ command: 'create procedure', procedure: string }
{ command: 'drop procedure', procedure: string }
{ command: 'call' }

// Plan de requête
{ command: 'explain', plan: string }

// DML
{ command: 'insert', result: Record<string, any>, rows: T[], fields: FieldInfo[] }
{ command: 'select', rows: T[], fields: { name: string, dataType: string }[] }
{ command: 'update', rowCount: number }
{ command: 'delete', rowCount: number }
{ command: 'copy', rowCount: number }

// Transactions
{ command: 'begin' }
{ command: 'commit' }
{ command: 'rollback' }

// Prepared statements
{ command: 'prepare', name: string }
{ command: 'deallocate', name: string }

Mapping de valeurs

Type SQL	Type JavaScript
INT, BIGINT, DOUBLE, NUMERIC	number
TEXT, CHAR, VARCHAR	string
BOOLEAN	boolean
UUID	string
TIMESTAMP	Date
ENUM	string (label)
Tableau JSON	Array
Objet JSON	Object
NULL	null