🌌 LDSS - Local Distributed Storage System

Store data in your users' browsers. Zero backend required.

Quick Start • Documentation • Examples • Contributing

⚠️ Experimental Release

LDSS v0.1.0 is an experimental proof-of-concept.

✅ Works in modern browsers (Chrome, Firefox, Safari, Edge)
✅ Great for prototypes and personal projects
⚠️ API may change in future versions
⚠️ Not battle-tested in production yet

Use at your own risk. Feedback and contributions welcome!

🎯 What is LDSS?

LDSS (Local Distributed Storage System) is a JavaScript library that lets you store data directly in your users' browsers using modern web APIs.

Why LDSS?

🚀 Zero Backend - No servers, no databases, no infrastructure costs
💰 Free Forever - Storage lives in user devices, not your servers
🔒 Privacy-First - Data never leaves the user's device
⚡ Blazing Fast - Direct access to local storage, no network latency
📦 Simple API - Store, retrieve, search - that's it

Perfect For

Personal projects and prototypes
Offline-first applications
Client-side tools and utilities
Learning modern web storage APIs
MVP development without backend

📦 Installation

Via NPM

npm install ldss-client

Via CDN

<script src="https://unpkg.com/ldss-client@0.1.0/ldss-client.js"></script>

Manual Download

Download ldss-client.js from GitHub Releases

🚀 Quick Start

1. Import LDSS

// ES6 Module
import LDSS from 'ldss-client';

// CommonJS
const LDSS = require('ldss-client');

// Browser (CDN)
// LDSS is available as window.LDSS

2. Initialize

const db = new LDSS({
  projectName: 'MyAwesomeApp'
});

await db.init();

3. Store Data

await db.store('todos', {
  title: 'Build something amazing',
  done: false
});

4. Retrieve Data

const todos = await db.getAll('todos');
console.log(todos);

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>LDSS Todo App</title>
</head>
<body>
  <h1>My Todos</h1>
  <input type="text" id="todoInput" placeholder="New todo...">
  <button onclick="addTodo()">Add</button>
  <ul id="todoList"></ul>

  <script src="https://unpkg.com/ldss-client@0.1.0/ldss-client.js"></script>
  <script>
    let db;

    async function initApp() {
      db = new LDSS({ projectName: 'TodoApp' });
      await db.init();
      await loadTodos();
    }

    async function addTodo() {
      const input = document.getElementById('todoInput');
      const title = input.value.trim();
      
      if (!title) return;

      await db.store('todos', {
        title,
        done: false,
        createdAt: Date.now()
      });

      input.value = '';
      await loadTodos();
    }

    async function loadTodos() {
      const todos = await db.getAll('todos');
      const list = document.getElementById('todoList');
      
      list.innerHTML = todos
        .map(todo => `<li>${todo.title}</li>`)
        .join('');
    }

    initApp();
  </script>
</body>
</html>

📚 Documentation

API Reference

`new LDSS(config)`

Create a new LDSS instance.

const db = new LDSS({
  projectName: 'MyApp' // Required: Unique name for your app
});

Parameters:

config.projectName (string, required) - Unique identifier for your application

`await db.init()`

Initialize LDSS workers. Must be called before any operations.

await db.init();

Returns: Promise - The initialized instance

`await db.store(collection, data)`

Store data in a collection.

await db.store('users', {
  name: 'Alice',
  email: 'alice@example.com'
});

Parameters:

collection (string) - Collection name
data (object) - Data to store

Returns: Promise<{ success: boolean, id: string }>

Auto-generated fields:

id - Unique identifier (auto-generated if not provided)
_createdAt - Timestamp when record was created

`await db.get(collection, id)`

Get a single item by ID.

const user = await db.get('users', 'user-123');
console.log(user);

Parameters:

collection (string) - Collection name
id (string|number) - Item ID

Returns: Promise<object|null> - The item or null if not found

`await db.getAll(collection)`

Get all items from a collection.

const allUsers = await db.getAll('users');
console.log(allUsers); // Array of user objects

Parameters:

collection (string) - Collection name

Returns: Promise - Array of items

`await db.delete(collection, id)`

Delete an item.

await db.delete('users', 'user-123');

Parameters:

collection (string) - Collection name
id (string|number) - Item ID

Returns: Promise<{ success: boolean }>

`await db.search(query)`

Search across all collections.

const results = await db.search('alice');
console.log(results);
// [{ collection: 'users', id: 'user-123', score: 100 }]

Parameters:

query (string) - Search query

Returns: Promise - Array of search results with scores

Searchable fields: title, name, text, content, description

`await db.clear(collection)`

Clear all data from a collection.

await db.clear('todos');

Parameters:

collection (string) - Collection name

Returns: Promise<{ success: boolean }>

`await db.getStats()`

Get storage statistics.

const stats = await db.getStats();
console.log(stats);
/*
{
  version: '0.1.0',
  projectName: 'MyApp',
  collections: 3,
  totalItems: 42,
  searchIndexSize: 42,
  estimatedSize: 43008
}
*/

Returns: Promise - Storage statistics

Architecture

LDSS v0.1.0 uses 3 specialized workers:

┌─────────────────────────────────────┐
│          LDSS Architecture          │
├─────────────────────────────────────┤
│                                     │
│  Worker 1: IndexedDB                │
│  ├─ Primary data storage            │
│  ├─ ~50 MB - 2 GB capacity          │
│  └─ Persistent across sessions      │
│                                     │
│  Worker 2: Cache (localStorage)     │
│  ├─ Fast access cache               │
│  ├─ ~5-10 MB capacity               │
│  └─ TTL-based expiration            │
│                                     │
│  Worker 3: Search (in-memory)       │
│  ├─ Full-text search index          │
│  ├─ Variable size                   │
│  └─ Rebuilt on page load            │
│                                     │
└─────────────────────────────────────┘

Storage Capacity:

Total: 50 MB - 2 GB (depends on browser)
Chrome/Edge: Up to 60% of free disk space
Firefox: Up to 10% of free disk space
Safari: Fixed ~1 GB limit

💡 Examples

🔧 Advanced Usage

Working with Multiple Collections

// Users collection
await db.store('users', { name: 'Alice' });
await db.store('users', { name: 'Bob' });

// Posts collection
await db.store('posts', { title: 'Hello World', author: 'Alice' });
await db.store('posts', { title: 'LDSS is awesome', author: 'Bob' });

// Get all users
const users = await db.getAll('users');

// Get all posts
const posts = await db.getAll('posts');

Custom IDs

// Provide your own ID
await db.store('users', {
  id: 'user_alice_2025',
  name: 'Alice'
});

// Retrieve by custom ID
const alice = await db.get('users', 'user_alice_2025');

Search with Auto-Indexing

// Store items with searchable fields
await db.store('articles', {
  title: 'Getting Started with LDSS',
  content: 'LDSS is a local storage system...',
  author: 'Anzize'
});

await db.store('articles', {
  title: 'Advanced LDSS Patterns',
  content: 'Learn how to build complex apps...',
  author: 'Anzize'
});

// Search across all articles
const results = await db.search('LDSS');
// Returns articles sorted by relevance

Error Handling

try {
  await db.store('users', { name: 'Alice' });
} catch (error) {
  console.error('Failed to store user:', error);
}

Storage Statistics

const stats = await db.getStats();
console.log(`
  Project: ${stats.projectName}
  Collections: ${stats.collections}
  Total Items: ${stats.totalItems}
  Search Index: ${stats.searchIndexSize} items
`);

🌐 Browser Support

Browser	Version	Support
Chrome	87+	✅ Full
Firefox	78+	✅ Full
Safari	14+	✅ Full
Edge	87+	✅ Full
Opera	73+	✅ Full

Requirements:

IndexedDB support
localStorage support
ES6+ JavaScript

🔒 Privacy & Security

Data Privacy

100% Client-Side: All data stays in the user's browser
No Tracking: LDSS doesn't send any...

Releases: Tryboy869/LDSS

LDSS v0.1.0 - Experimental Release

🌌 LDSS - Local Distributed Storage System

⚠️ Experimental Release

🎯 What is LDSS?

Why LDSS?

Perfect For

📦 Installation

Via NPM

Via CDN

Manual Download

🚀 Quick Start

1. Import LDSS

2. Initialize

3. Store Data

4. Retrieve Data

Complete Example

📚 Documentation

API Reference

new LDSS(config)

await db.init()

await db.store(collection, data)

await db.get(collection, id)

await db.getAll(collection)

await db.delete(collection, id)

await db.search(query)

await db.clear(collection)

await db.getStats()

Architecture

💡 Examples

Example 1: Todo App

Example 2: Notes App

Example 3: Contacts Manager

🔧 Advanced Usage

Working with Multiple Collections

Custom IDs

Search with Auto-Indexing

Error Handling

Storage Statistics

🌐 Browser Support

🔒 Privacy & Security

Data Privacy

Uh oh!

`new LDSS(config)`

`await db.init()`

`await db.store(collection, data)`

`await db.get(collection, id)`

`await db.getAll(collection)`

`await db.delete(collection, id)`

`await db.search(query)`

`await db.clear(collection)`

`await db.getStats()`