PicassoDB Client Library

A comprehensive JavaScript client for PicassoDB HTTP APIs, supporting both browser and Node.js environments with seamless session and cookie management.

Installation

Install via npm:

npm install @picassodb/client

Key Features

• Unified API: Connect, disconnect, CRUD operations, and more through a consistent interface.
• Automatic Session Persistence: Node.js clients automatically save and restore cookies using SessionStore.
• Browser Compatibility: Built on axios with withCredentials for effortless use in web apps.
• Token Refresh Handling: Transparently retries expired tokens without manual intervention.

Quick Start

Importing the Library

// ES Modules
import { BrowserClient, NodeClient } from 'picassodb-client';

// CommonJS
const { BrowserClient, NodeClient } = require('picassodb-client');

Browser Example

const client = new BrowserClient({
  apiUrl: 'https://api.example.com',
  credentials: { user: '[email protected]', password: 'secret' }
});

(async () => {
  try {
    // Authenticate and start a session
    await client.connect();

    // List existing databases
    const databases = await client.listDatabases();
    console.log('Databases:', databases);

    // Create a new database
    await client.createDatabase('test_db');
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Logout and clear the session
    await client.disconnect();
  }
})();

Node.js Example

import { NodeClient } from 'picassodb-client';

const client = new NodeClient({
  apiUrl: 'https://api.example.com',
  credentials: { user: '[email protected]', password: 'secret' },
  ppid: process.pid  // Unique process identifier for session storage
});

(async () => {
  try {
    // Reuse saved session if available
    await client.connect();

    // Perform authenticated operations
    const tables = await client.listTables('test_db');
    console.log('Tables:', tables);

    // Insert a new record
    await client.createRecord('test_db', 'users', { name: 'Alice', email: '[email protected]' });
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Clean up session data
    await client.disconnect();
  }
})();

API Reference

All methods return Promises. Errors are thrown as PicassoClientError.

Constructors

• BrowserClient

  new BrowserClient({ apiUrl, credentials })

• NodeClient

  new NodeClient({ apiUrl, credentials, ppid })

Core Methods

| Method | Description | | --------------------- | ------------------------------------------------------------------ | | connect(overrides?) | Authenticate; returns { accessToken, refreshToken?, expiresIn? } | | disconnect() | Log out and clear session data | | getConnectionInfo() | Retrieve current connection status and credentials |

Database Operations

| Method | Description | | ---------------------------------------- | --------------------------- | | listDatabases() | List all databases | | createDatabase(name, user?, setupApi?) | Create a new database | | dropDatabase(name) | Delete an existing database |

Table Operations

| Method | Description | | ------------------------------------------- | ------------------------------------- | | listTables(database) | List tables in a database | | createTable(database, tableName, columns) | Create a table with specified columns | | dropTable(database, tableName) | Drop a table |

Record Operations

| Method | Description | | --------------------------------------------- | --------------------------------------- | | listRecords(database, table, query?) | Retrieve records with optional filters | | createRecord(database, table, data) | Insert a single record | | insertRecords(database, table, records) | Insert multiple records | | deleteRecords(database, table, conditions) | Soft-delete records matching conditions | | restoreRecords(database, table, conditions) | Restore previously deleted records |

Import/Export

| Method | Description | | -------------------------------------------------------- | -------------------------------- | | importCSV(database, tableName, filePath) | Import records from a CSV file | | importJSON(database, tableName, filePath) | Import records from a JSON file | | importXLSX(database, tableName, filePath, sheet?) | Import records from an XLSX file | | exportCSV(tableName, records, outputPath) | Export records to a CSV file | | exportJSON(tableName, records, outputPath) | Export records to a JSON file | | exportXLSX(tableName, records, outputPath, sheetName?) | Export records to an XLSX file |

NodeClient automatically manages cookie storage in ~/.picassodb/sessions/<ppid>.json, preserving sessions across restarts.

Session Persistence (Node.js)

NodeClient automatically manages cookie storage in ~/.picassodb/sessions/<ppid>.json, preserving sessions across restarts.