Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LibSqlPersistence
✓ import { LibSqlPersistence } from 'awaitly-libsql'
✗ const { LibSqlPersistence } = require('awaitly-libsql')
Package is ESM-only. CJS require will fail. Use dynamic import() if needed.
createLibSqlPersistence
✓ import { createLibSqlPersistence } from 'awaitly-libsql/client'
✗ import { createLibSqlPersistence } from 'awaitly-libsql'
Factory function is exported from 'awaitly-libsql/client' subpath import.
RemapOptions
✓ import type { RemapOptions } from 'awaitly-libsql/types'
Type imports require 'awaitly-libsql/types' subpath.
Set up an awaitly workflow runtime with libSQL persistence, showing client creation, adapter instantiation, workflow registration, and starting the runtime.
import { LibSqlPersistence } from 'awaitly-libsql';
import { createClient } from '@libsql/client';
import { WorkflowRuntime } from 'awaitly';
// Initialize libSQL client (local file or Turso remote)
const client = createClient({
url: process.env.LIBSQL_URL ?? 'file:./workflows.db',
authToken: process.env.LIBSQL_AUTH_TOKEN ?? '',
});
// Create persistence adapter
const persistence = new LibSqlPersistence(client);
// Create workflow runtime with persistence
const runtime = new WorkflowRuntime({
persistence,
});
// Define a simple workflow
runtime.registerWorkflow('hello', async (ctx) => {
const name = await ctx.waitForEvent('name');
console.log(`Hello, ${name}!`);
});
// Start runtime
await runtime.start();
console.log('Workflow runtime started. Press Ctrl+C to stop.');
Debug
Known issues
breakingIn v22.0.0, the import path for createLibSqlPersistence changed from 'awaitly-libsql' to 'awaitly-libsql/client'.fixUpdate imports to use 'awaitly-libsql/client'.
affects: >=22.0.0 <23.0.0
breakingIn v23.0.0, the 'tablePrefix' option in constructor was removed. Use 'PersistenceOptions.tablePrefix' instead.fixPass tablePrefix inside options object: new LibSqlPersistence(client, { tablePrefix: 'myapp_' }) affects: >=23.0.0
deprecatedThe 'createClient' function from 'awaitly-libsql' is deprecated. Use '@libsql/client' directly.fixInstall @libsql/client and import createClient from '@libsql/client'.
affects: >=20.0.0
gotchaIf using Turso remote database, ensure the 'LIBSQL_AUTH_TOKEN' environment variable is set. Missing token causes silent retries and eventual timeout.fixSet LIBSQL_AUTH_TOKEN in environment or pass authToken in client options.
affects: >=18.0.0
breakingNode.js >=22 is required. Using an older version will throw an engine error.fixUpgrade Node.js to version 22 or later.
affects: >=23.0.0
gotchaThe 'awaitly' peer dependency must be version ^1.34.0. Mixing major versions will cause runtime errors.fixEnsure awaitly@^1.34.0 is installed.
affects: >=23.0.0
deprecatedThe 'type' parameter in workflow registration is deprecated; use the 'events' config instead.fixRemove 'type' from registration and use 'events' property in config object.
affects: >=19.0.0
Errors
Common errors & fixes
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'awaitly-libsql/client'
Importing from subpath 'awaitly-libsql/client' without proper package.json exports.
fixEnsure package version is >=22.0.0 and Node.js supports subpath imports. If not, import from 'awaitly-libsql' and use LibSqlPersistence directly.
TypeError: LibSqlPersistence is not a constructor
Using CommonJS require() on an ESM-only package.
fixChange to ES module import: import { LibSqlPersistence } from 'awaitly-libsql' Error: No persistence adapter provided
Missing 'persistence' option when constructing WorkflowRuntime.
fixPass persistence instance to runtime options: new WorkflowRuntime({ persistence }) SQLITE_ERROR: no such table: workflows
Tables are not automatically created; LibSqlPersistence expects schema to be applied.
fixCall persistence.ensureTables() before starting the runtime.
Error: LIBSQL_URL environment variable not set
The libSQL client requires a URL to connect.
fixSet LIBSQL_URL environment variable or pass url in createClient options.
Audit
Dependencies
awaitlyrequiredPeer dependency required to provide workflow engine runtime.