UDSL - Universal Data Safety Layer

Crash-safe persistence layer powered by Write-Ahead Logging (WAL) and Snapshots.

UDSL helps applications recover instantly after crashes while maintaining a complete audit trail of state changes.

Features

• Write-Ahead Logging (WAL)
• Snapshot-based Recovery
• Crash-safe State Persistence
• Instant Recovery Engine
• Audit Logging
• Multi-Tenant Support
• Docker-powered Server
• TypeScript SDK

Installation

Install the SDK:

npm install udsl-sdk

Prerequisites

Before using UDSL, make sure you have:

• Node.js 18+
• Docker Desktop installed and running

Download Docker:

https://www.docker.com/products/docker-desktop/

Start UDSL Server

Start the server using the CLI:

npx udsl-sdk start

This command automatically:

• Pulls the latest UDSL Docker image
• Creates a container named udsl-server
• Starts the server on port 3001

Expected output:

🚀 Starting UDSL...
📦 Pulling UDSL image...
🔥 Starting server...
✅ UDSL running at http://localhost:3001

Starting an Existing Server

After the first setup, you can simply run:

docker start udsl-server

No need to run npx udsl-sdk start every time.

Stopping the Server

docker stop udsl-server

Basic Usage

const { UDSL } = require("udsl-sdk");

UDSL.init({
  baseUrl: "http://localhost:3001",
  apiKey: "test-key-123"
});

async function main() {
  await UDSL.save("companyA:user1", {
    name: "Om",
    age: 22
  });

  const result = await UDSL.get("companyA:user1");

  console.log(result);
}

main();

Output:

{
  key: "companyA:user1",
  state: {
    name: "Om",
    age: 22
  },
  eventsCount: 1,
  mode: "INSTANT_RECOVERY"
}

Recovery Example

Save data:

await UDSL.save("companyA:profile", {
  name: "Om",
  city: "Mumbai"
});

Stop the server:

docker stop udsl-server

Restart:

docker start udsl-server

Read data again:

const data = await UDSL.get("companyA:profile");

Your data is automatically recovered from snapshots and WAL.

Docker Image

UDSL Server Image:

docker pull omghadage/udsl-server:latest

Manual start:

docker run -d -p 3001:3001 --name udsl-server omghadage/udsl-server:latest

Architecture

Application
     │
     ▼
  udsl-sdk
     │
     ▼
 UDSL Server
     │
 ┌───┼─────────┐
 │   │         │
 ▼   ▼         ▼

WAL Snapshot Audit
Log  Store    Log

Data Flow

1. Application sends state updates.
2. UDSL appends events to WAL.
3. Events update in-memory state.
4. Periodic snapshots are created.
5. Recovery loads snapshot first.
6. Recent WAL entries are replayed.
7. State is restored instantly.

Example Use Cases

• Notes Applications
• Offline-first Apps
• Document Editors
• Workflow Engines
• State Synchronization
• Audit-heavy Systems
• Recovery-critical Applications

Troubleshooting

Port 3001 already allocated

Find running containers:

docker ps

Stop existing server:

docker stop udsl-server

Or remove it:

docker rm -f udsl-server

Docker not running

Start Docker Desktop and retry:

npx udsl-sdk start

Author

Om Ghadage

License

MIT