@yihuangdb/storage-object
Version:
A Node.js storage object layer library using Redis OM
315 lines • 8.11 kB
JavaScript
"use strict";
/**
* @module quick-start
* @description Simplified API for quick prototyping and simple use cases.
*
* This module provides the simplest possible API for using StorageObject.
* Perfect for prototypes, scripts, and applications that don't need advanced features.
*
* @example
* ```typescript
* import { storage } from '@yihuangdb/storage-object/quick';
*
* // Create a storage with just field types
* const users = await storage('users', {
* name: 'text',
* email: 'string',
* age: 'number'
* });
*
* // CRUD operations
* const user = await users.create({ name: 'John', email: 'john@example.com', age: 30 });
* const found = await users.findById(user.entityId);
* await users.update(user.entityId, { age: 31 });
* await users.delete(user.entityId);
* ```
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.QuickStart = void 0;
exports.storage = storage;
exports.quick = quick;
exports.define = define;
exports.connect = connect;
exports.list = list;
exports.remove = remove;
exports.clear = clear;
const storage_system_1 = require("./storage-system");
/**
* Create or get a storage with minimal configuration.
*
* This is the simplest way to create a storage. It automatically:
* - Creates the storage if it doesn't exist
* - Returns the existing storage if it does
* - Indexes all fields by default
* - Uses JSON storage mode
* - Enables optimistic locking
*
* @param name - Name of the storage
* @param schema - Simple schema definition (just field types)
* @returns Promise resolving to the storage instance
*
* @example
* ```typescript
* // Super simple - just field types
* const users = await storage('users', {
* name: 'text',
* email: 'string',
* age: 'number',
* isActive: 'boolean',
* tags: 'string[]',
* createdAt: 'date'
* });
*
* // Start using it immediately
* await users.create({
* name: 'John',
* email: 'john@example.com',
* age: 30,
* isActive: true
* });
* ```
*/
async function storage(name, schema) {
// Check if storage already exists
const existing = await storage_system_1.StorageSystem.get(name);
if (existing) {
return existing;
}
// Storage doesn't exist and no schema provided
if (!schema) {
throw new Error(`Storage '${name}' not found. Provide a schema to create it:\n` +
`Example: storage('${name}', { name: 'text', email: 'string' })`);
}
// Convert simple schema to full schema config (with all fields indexed by default)
const schemaConfig = {};
for (const [field, type] of Object.entries(schema)) {
schemaConfig[field] = {
type,
indexed: true // Index everything by default for convenience
};
}
// Create the storage with sensible defaults
return storage_system_1.StorageSystem.create(name, schemaConfig, {
useJSON: true,
enableOptimisticLocking: true
});
}
/**
* Quick storage creation with inline operations.
*
* @param name - Name of the storage
* @returns Object with storage operations
*
* @example
* ```typescript
* const { create, find, update, remove } = quick('users');
*
* // Define schema on first create
* const user = await create(
* { name: 'John', email: 'john@example.com' },
* { name: 'text', email: 'string' } // Schema only needed once
* );
*
* // Subsequent operations don't need schema
* const users = await find({ name: 'John' });
* await update(user.entityId, { email: 'newemail@example.com' });
* await remove(user.entityId);
* ```
*/
function quick(name) {
let storageInstance = null;
const getStorage = async (schema) => {
if (!storageInstance) {
storageInstance = await storage(name, schema);
}
return storageInstance;
};
return {
/**
* Create a new entity
*/
create: async (data, schema) => {
const s = await getStorage(schema);
return s.create(data);
},
/**
* Find entities by query
*/
find: async (query) => {
const s = await getStorage();
return s.find(query);
},
/**
* Find one entity by query
*/
findOne: async (query) => {
const s = await getStorage();
return s.findOne(query);
},
/**
* Find entity by ID
*/
findById: async (id) => {
const s = await getStorage();
return s.findById(id);
},
/**
* Find all entities
*/
findAll: async () => {
const s = await getStorage();
return s.findAll();
},
/**
* Update entity by ID
*/
update: async (id, data) => {
const s = await getStorage();
return s.update(id, data);
},
/**
* Delete entity by ID
*/
remove: async (id) => {
const s = await getStorage();
return s.delete(id);
},
/**
* Count entities
*/
count: async () => {
const s = await getStorage();
return s.count();
},
/**
* Clear all data
*/
clear: async () => {
const s = await getStorage();
return s.clear();
},
/**
* Get the underlying storage instance for advanced operations
*/
instance: async () => {
return getStorage();
}
};
}
/**
* Define a typed storage schema for better TypeScript support.
*
* @example
* ```typescript
* interface User {
* name: string;
* email: string;
* age: number;
* isActive: boolean;
* }
*
* const userSchema = define<User>({
* name: 'text',
* email: 'string',
* age: 'number',
* isActive: 'boolean'
* });
*
* const users = await storage<User>('users', userSchema);
*
* // Now TypeScript knows the shape of your data
* const user = await users.create({
* name: 'John',
* email: 'john@example.com',
* age: 30,
* isActive: true
* });
* ```
*/
function define(schema) {
return schema;
}
/**
* Connect to Redis with custom configuration.
* Optional - StorageObject uses default localhost connection if not called.
*
* @param config - Redis connection options
*
* @example
* ```typescript
* // Connect to custom Redis instance
* await connect({
* host: 'redis.example.com',
* port: 6379,
* password: 'secret'
* });
*
* // Now all storage operations will use this connection
* const users = await storage('users', { name: 'text' });
* ```
*/
async function connect(config) {
await storage_system_1.StorageSystem.initialize({
redis: config,
defaultOptions: {
useJSON: true,
enableOptimisticLocking: true
}
});
}
/**
* List all available storages.
*
* @returns Array of storage names
*
* @example
* ```typescript
* const names = await list();
* console.log('Available storages:', names);
* // ['users', 'products', 'orders']
* ```
*/
async function list() {
return storage_system_1.StorageSystem.names();
}
/**
* Delete a storage and all its data.
*
* @param name - Name of the storage to delete
* @returns True if deleted, false if not found
*
* @example
* ```typescript
* await remove('old-storage');
* ```
*/
async function remove(name) {
return storage_system_1.StorageSystem.delete(name);
}
/**
* Clear all data from a storage without deleting it.
*
* @param name - Name of the storage to clear
*
* @example
* ```typescript
* await clear('users');
* console.log('All user data cleared');
* ```
*/
async function clear(name) {
return storage_system_1.StorageSystem.clear(name);
}
// Export everything as a namespace for convenience
exports.QuickStart = {
storage,
quick,
define,
connect,
list,
remove,
clear
};
// Default export for simplest import
exports.default = storage;
//# sourceMappingURL=quick-start.js.map