LevelGraph - Graph Database

Common errors

• Error: Cannot find module 'level-browserify'

  cause This error typically occurs when using LevelGraph versions prior to 3.0.0 with newer Node.js environments, where the deprecated `level-browserify` package had installation issues.
  fix Upgrade `levelgraph` to version 3.0.0 or higher. This version replaces `level-browserify` with the more compatible `level` package.

• TypeError: Object.keys called on non-object

  cause Reported in older versions (fixed in v1.1.3), this error indicates that a non-object value was passed where an object (e.g., a triple pattern) was expected, causing `Object.keys()` to fail.
  fix Ensure that all arguments expected to be objects (like triple patterns for `db.get` or `db.put`) are indeed valid JavaScript objects. If you are on an older version, upgrade to `levelgraph` v1.1.3 or newer.

• Error: The 'path' argument must be of type string. Received undefined

  cause This is a common error from the underlying `level` library when its constructor `new Level()` is called without a valid string path for the database directory.
  fix Always provide a valid, non-empty string path when initializing `new Level('your-database-path')`. Ensure your database path variable is correctly defined and not `null` or `undefined`.

Warnings

• breaking LevelGraph v4.0.0 updates its internal `level` dependency to v8. This update can introduce breaking changes from the `level` library itself, particularly regarding its asynchronous API and potential Node.js version requirements. Ensure compatibility with your existing `level` usage.
  Fix: Review the changelog for `level` v8 for specific breaking changes. Update your `level` related code if directly interacting with the `level` API used by LevelGraph. Test thoroughly after upgrading.
• breaking In v3.0.0, `level-browserify` was replaced by `level` as the underlying store for browser environments. `level-browserify` was noted to have installation issues on newer Node.js versions, making this a critical upgrade for compatibility.
  Fix: Upgrade to LevelGraph v3.0.0 or later to leverage the `level` package which offers better compatibility and browser support. If you were explicitly using `level-browserify` in your build, switch to `level`.
• gotcha Stream closing behavior for internal tests in v3.0.0 was changed from listening to the `close` event to the `end` event due to double-triggering. While this primarily affected internal tests, developers relying on specific stream lifecycle events in their own code might experience different behavior.
  Fix: If your application code directly interacts with streams returned by LevelGraph and relies on `close` or `end` events, review your stream handling logic for potential subtle behavioral changes after upgrading to v3.0.0.
• gotcha LevelGraph officially tests only against Node.js versions 18 and 20. While other versions may function, their support is not guaranteed, and compatibility issues might arise.
  Fix: For production deployments, target Node.js 18 or 20. If using other versions, ensure comprehensive testing of your application's LevelGraph interactions.

Install

• npm install levelgraph npm
• yarn add levelgraph yarn
• pnpm add levelgraph pnpm

Imports

• levelgraph
  wrong:

  import levelgraph from 'levelgraph';

  correct:

  const levelgraph = require('levelgraph');

  LevelGraph's primary entry point is a CommonJS module exporting a factory function. While Node.js supports ESM, the package itself is not a pure ESM module. For modern ESM environments, consider using a CommonJS compatibility wrapper or a bundler.
• Level
  wrong:

  import { Level } from 'level';

  correct:

  const { Level } = require('level');

  The underlying `level` dependency itself supports both CommonJS and ESM. LevelGraph's examples currently show CommonJS `require` for `Level` as well.
• db.put
  wrong:

  db.put('s', 'p', 'o', callback);

  correct:

  db.put({ subject: 's', predicate: 'p', object: 'o' }, callback);

  Triples must be provided as an object with `subject`, `predicate`, and `object` properties.

Quickstart

This quickstart demonstrates how to initialize a LevelGraph database, insert a triple, retrieve it using a pattern match, and then properly clean up the database resources.

const { Level } = require('level');
const levelgraph = require('levelgraph');
const path = require('path');
const os = require('os');
const fs = require('fs');

// Create a temporary directory for the database
const dbPath = path.join(os.tmpdir(), `levelgraph-test-${Date.now()}`);

// Initialize the database with a LevelDB store
const db = levelgraph(new Level(dbPath));

const triple = { subject: 'book', predicate: 'hasAuthor', object: 'Alice' };

db.put(triple, function(err) {
  if (err) {
    console.error('Error putting triple:', err);
    return;
  }
  console.log('Triple inserted:', triple);

  // Retrieve triples matching a pattern
  db.get({ subject: 'book', predicate: 'hasAuthor' }, function(err, triples) {
    if (err) {
      console.error('Error getting triples:', err);
      return;
    }
    console.log('Retrieved triples:', triples);
    // Expected output: [{ subject: 'book', predicate: 'hasAuthor', object: 'Alice' }]

    // Clean up: close the database and remove the directory
    db.close(function(closeErr) {
      if (closeErr) console.error('Error closing db:', closeErr);
      else console.log('Database closed.');
      fs.rm(dbPath, { recursive: true, force: true }, (rmErr) => {
        if (rmErr) console.error('Error removing database directory:', rmErr);
        else console.log('Database directory removed.');
      });
    });
  });
});