Skip to content

API.md

Latest commit

 

History

History
497 lines (343 loc) · 9.38 KB

API.md

File metadata and controls

497 lines (343 loc) · 9.38 KB
Raw

API Reference

Table of Contents

UnifiedDB

The main database class that provides cross-platform database functionality.

Constructor

new UnifiedDB(config?, options?)

Parameters:

  • config (Object, optional): Database configuration object
  • options (Object, optional): Database options

Options:

  • autoInit (boolean, default: true): Automatically initialize the database
  • storageType (string, default: 'auto'): Force specific storage backend
  • storage (Object): Storage backend specific options

Methods

init()

Initialize the database and storage backend.

await db.init()

Returns: Promise<void>

create(modelName, data)

Create a new record in the specified model.

const user = await db.create('User', {
  name: 'John Doe',
  email: 'john@example.com'
})

Parameters:

  • modelName (string): Name of the model
  • data (Object): Data to create

Returns: Promise<Object> - Created record

findUnique(modelName, where)

Find a single record matching the criteria.

const user = await db.findUnique('User', { id: 'user123' })

Parameters:

  • modelName (string): Name of the model
  • where (Object): Search criteria

Returns: Promise<Object|null> - Found record or null

update(modelName, where, data)

Update a record matching the criteria.

const updatedUser = await db.update('User', 
  { id: 'user123' }, 
  { name: 'Jane Doe' }
)

Parameters:

  • modelName (string): Name of the model
  • where (Object): Search criteria
  • data (Object): Update data

Returns: Promise<Object|null> - Updated record or null

updateMany(modelName, where, data)

Update multiple records matching the criteria.

const updatedUsers = await db.updateMany('User', 
  { active: false }, 
  { status: 'inactive' }
)

Parameters:

  • modelName (string): Name of the model
  • where (Object): Search criteria
  • data (Object): Update data

Returns: Promise<Array> - Array of updated records

delete(modelName, where)

Delete a record matching the criteria.

const deletedUser = await db.delete('User', { id: 'user123' })

Parameters:

  • modelName (string): Name of the model
  • where (Object): Search criteria

Returns: Promise<Object|null> - Deleted record or null

deleteMany(modelName, where)

Delete multiple records matching the criteria.

const deletedUsers = await db.deleteMany('User', { active: false })

Parameters:

  • modelName (string): Name of the model
  • where (Object): Search criteria

Returns: Promise<Array> - Array of deleted records

addHook(hookName, hookFunction)

Add a hook for database operations.

db.addHook('beforeCreate', (modelName, data) => {
  console.log(`Creating ${modelName}:`, data)
  return data
})

Parameters:

  • hookName (string): Hook name ('beforeCreate', 'afterCreate', etc.)
  • hookFunction (Function): Hook function

clearAll()

Clear all data from the database.

await db.clearAll()

Returns: Promise<void>

export()

Export all database data.

const backup = await db.export()

Returns: Promise<Object> - Database export

import(data, options?)

Import data into the database.

await db.import(backup, { clearFirst: true })

Parameters:

  • data (Object): Data to import
  • options (Object, optional): Import options
    • clearFirst (boolean): Clear database before import
    • validateConfig (boolean): Validate configuration compatibility

Returns: Promise<void>

getStats()

Get database statistics.

const stats = await db.getStats()

Returns: Promise<Object> - Database statistics

close()

Close the database connection.

await db.close()

Returns: Promise<void>

Configuration

Database Configuration

const config = {
  models: {
    User: {
      fields: {
        id: { type: 'string', primaryKey: true },
        name: { type: 'string', required: true },
        email: { type: 'string', unique: true },
        age: { type: 'number', default: 0 },
        createdAt: { type: 'date', default: 'now' }
      }
    }
  },
  settings: {
    autoId: true,
    timestamps: true,
    validation: true,
    encryption: false
  },
  version: '1.0.0'
}

Field Types

  • string: Text data
  • number: Numeric data
  • boolean: True/false values
  • date: Date/time values
  • array: Array data
  • object: Object data

Field Options

  • primaryKey (boolean): Mark as primary key
  • required (boolean): Field is required
  • unique (boolean): Field must be unique
  • default (any|Function): Default value or function
  • validate (Function): Custom validation function

Settings

  • autoId (boolean): Automatically generate IDs
  • timestamps (boolean): Add createdAt/updatedAt fields
  • validation (boolean): Enable data validation
  • encryption (boolean): Enable data encryption

Model Clients

Model clients provide a Prisma-like API for each model.

Available Methods

// Access model client
const userClient = db.user // or db.User

// Create
const user = await db.user.create({ name: 'John' })

// Find unique
const user = await db.user.findUnique({ id: 'user123' })

// Find many with query builder
const users = await db.user.findMany({
  where: { age: { gte: 18 } },
  orderBy: { name: 'asc' },
  take: 10,
  skip: 0
})

// Update
const user = await db.user.update(
  { id: 'user123' }, 
  { name: 'Jane' }
)

// Delete
const user = await db.user.delete({ id: 'user123' })

// Count
const count = await db.user.count({ active: true })

QueryBuilder

Advanced query building with method chaining.

Methods

where(field, operator?, value)

Add where conditions.

query.where('name', 'John')
query.where('age', '>', 18)
query.where('email', 'contains', '@gmail.com')

Operators:

  • equals (default)
  • not
  • gt, gte, lt, lte
  • contains, startsWith, endsWith
  • in, notIn
  • isNull, isNotNull
  • isEmpty, isNotEmpty
  • regex

orderBy(field, direction?)

Add ordering.

query.orderBy('name', 'asc')
query.orderBy('createdAt', 'desc')

limit(count) / take(count)

Limit results.

query.limit(10)
query.take(10) // Prisma-style alias

offset(count) / skip(count)

Skip results.

query.offset(20)
query.skip(20) // Prisma-style alias

select(fields)

Select specific fields.

query.select(['name', 'email'])
query.select({ name: true, email: true })

include(relation)

Include related data.

query.include('posts')
query.include({ posts: { where: { published: true } } })

Execution Methods

findMany()

Execute query and return multiple results.

const users = await query.findMany()

findFirst()

Execute query and return first result.

const user = await query.findFirst()

findUnique()

Execute query expecting exactly one result.

const user = await query.findUnique()

count()

Count matching records.

const count = await query.count()

EnvironmentDetector

Utility for detecting the runtime environment.

Methods

detect()

Detect current environment.

const env = EnvironmentDetector.detect()
// Returns: 'browser' | 'node' | 'electron' | 'react-native' | 'unknown'

is(environment)

Check if running in specific environment.

const isBrowser = EnvironmentDetector.is('browser')

getCapabilities()

Get environment capabilities.

const capabilities = EnvironmentDetector.getCapabilities()
// Returns object with capability flags

Storage Backends

LocalStorageBackend

Browser localStorage implementation.

Environment: Browser
Capacity: ~5-10MB
Persistence: Until cleared by user

IndexedDBBackend

Browser IndexedDB implementation.

Environment: Browser
Capacity: ~50MB+ (quota-based)
Persistence: Until cleared by user

FileSystemBackend

Node.js/Electron file system implementation.

Environment: Node.js, Electron
Capacity: Disk space limited
Persistence: Permanent

AsyncStorageBackend

React Native AsyncStorage implementation.

Environment: React Native
Capacity: Platform dependent
Persistence: Until app uninstalled

Error Handling

All async methods can throw errors. Always use try-catch:

try {
  const user = await db.user.create({ name: 'John' })
} catch (error) {
  console.error('Database error:', error.message)
}

Hooks

Available hooks for extending functionality:

  • beforeCreate - Before creating records
  • afterCreate - After creating records
  • beforeUpdate - Before updating records
  • afterUpdate - After updating records
  • beforeDelete - Before deleting records
  • afterDelete - After deleting records
db.addHook('beforeCreate', async (modelName, data) => {
  // Modify data before creation
  data.createdBy = getCurrentUser()
  return data
})