@afranioalves/memory-client
v1.0.5
Published
A simple memory management system using indexedDB files.
Maintainers
afranioReadme
@afranioalves/memory-client
Lightweight library for client-side data storage. It offers a simple asynchronous API to create, read, and delete data by key.
Version: 1.0.5
Description
This library exposes a singleton instance that simplifies basic storage operations in the browser. It is designed for use in front-end applications (e.g., web pages, React, Next.js).
Main features:
- Automatic initialization.
- Simple async methods:
create,read,delete.
Installation
Install via npm or yarn:
npm install @afranioalves/memory-client
# or
yarn add @afranioalves/memory-clientNote: The package uses ES modules (package.json has "type": "module").
Quick Usage
Import the default instance and call the async methods:
import Memory from '@afranioalves/memory-client';
async function main() {
// Create a memory
const createResult = await Memory.create('my-key', { name: 'Afrânio', age: 18 });
console.log(createResult);
// Read the memory
const value = await Memory.read('my-key');
console.log('read value:', value);
// Delete the memory
const deleteResult = await Memory.delete('my-key');
console.log(deleteResult);
}
main();HTML Example (browser)
<!doctype html>
<html>
<head><meta charset="utf-8"><title>Memory Example</title></head>
<body>
<script type="module">
import Memory from '/node_modules/@afranioalves/memory-client/src/index.js';
(async () => {
console.log(await Memory.create('ex1', 'Hello World'));
console.log(await Memory.read('ex1'));
console.log(await Memory.delete('ex1'));
})();
</script>
</body>
</html>Note: When using bundlers or frameworks (Vite, Webpack, Next.js), prefer importing by package name:
import Memory from '@afranioalves/memory-client'.
React Example
import React from 'react';
import Memory from '@afranioalves/memory-client';
export default function App() {
const createMemory = async () => {
const result = await Memory.create('user', { name: 'Ana' });
console.log(result);
};
const readMemory = async () => {
const user = await Memory.read('user');
console.log(user);
};
return (
<div>
<button onClick={createMemory}>Create Memory</button>
<button onClick={readMemory}>Read Memory</button>
Check the console for results.
</div>
);
}API
All methods are asynchronous and return Promises.
create(memoryName, memoryValue)- Description: Creates an entry with key
memoryNameand valuememoryValue. - Returns: Promise resolving to an object
{ message: string, status: number }on success, or rejects on error. - Example status codes:
201(created successfully),409(already exists),500(internal error).
- Description: Creates an entry with key
read(memoryName)- Description: Reads the stored value for
memoryName. - Returns: Promise resolving to the value (any stored data) or
{ message, status }when not found or on error (e.g.,404when not found,500on internal error).
- Description: Reads the stored value for
delete(memoryName)- Description: Deletes the entry with key
memoryName. - Returns: Promise resolving to
{ message: string, status: number }.
- Description: Deletes the entry with key
Example responses:
- Successful creation:
{ message: 'Memory my-key created successfully.', status: 201 } - Not found:
{ message: 'Memory my-key does not exist.', status: 404 }(or the stored value when it exists)
Updates
Exciting New Features
- Database Class: A powerful new addition for structured data storage, allowing for more complex data management.
- Table Management: Easily create tables and define their structure with just a few lines of code.
With the Database from memory-client, data manipulation becomes easier. The data will be stored in a structure similar to a table, making it easier to perform CRUD (create, read, update, delete) operations.
| name | email | age | |------------------------|-----------------------------------------|------------------------| | Hugo Jorge | [email protected] | 30| | Afrânio Alves | [email protected] | 18 | | Andrade Antunes | [email protected] | 20 |
Enhanced Usage Example
import Memory, { Database as database, type IColumn } from '@afranioalves/memory-client'
const App = () => {
// Create a new table for users with an auto-incrementing ID
const createTable = async () => {
const columns: IColumn[] = [
{ name: 'nome', type: 'string', unique: false },
{ name: 'email', type: 'string', unique: true, },
{ name: 'age', type: 'number', unique: false }
]
// id is the primary key of this table.
const result = await database.createTable('users', 'id', true, columns)
console.log(result)
}
// Insert a new user into the table
const insertData = async () => {
const data = {
nome: "Hugo Jorge",
email: "[email protected]",
age: 30,
}
const result = await database.insert("users", data);
console.log(result)
}
// find all data
const findAll = async () => {
const users = await database.selectAll('users')
console.log('users', users)
}
// find for a record
const findOne = async () => {
// email is the field where the search
const user = await database.selectOne('users', 'email', '[email protected]')
console.log(user)
}
// updates a record
const updatedData = async () => {
const newValue = {email:'[email protected]'}
const result = await database.update('users', 'email','[email protected]', newValue)
console.log(result)
}
const deleteData = async () => {
const result = await database.delete('users', 1)
console.log(result)
}
}
export default App;
Notes and Common Issues
- This library is intended for client-side (browser) use. Persistence behavior may vary slightly between environments/browsers.
- In contexts with very strict privacy policies or special browser modes, storage may be limited or temporary.
@afranioalves/memory-client vs localStorage
| Feature | @afranioalves/memory-client | localStorage | |------------------------|-----------------------------------------|------------------------| | Storage Limit | Large (hundreds of MBs) | Small (~5MB per origin)| | Data Type Support | Any JS type (objects, arrays, etc.) | Only strings | | Async API | Yes (Promises) | No (synchronous) | | Performance | Fast for large/bulk data | Fast for small data | | Transactions | Supported | Not supported | | Browser Support | All modern browsers | All browsers | | Use Cases | Complex, structured, or large data | Simple key-value pairs | | API Complexity | Simple via this library | Very simple | | Persistence | Persistent, survives browser restarts | Persistent |
When to use @afranioalves/memory-client
- You need to store objects, arrays, or non-string data.
- You expect to store more than a few megabytes.
- You want async operations and better performance for large datasets.
- You need transactional integrity.
When to use localStorage
- You only need to store small amounts of string data.
- You want a synchronous, simple API for quick tasks.
- You do not need to store complex or large data.
License
MIT — see the LICENSE file
Author: Afrânio Alves