Aerospike ORM for NodeJS

A TypeScript utility library for working with Aerospike using entities and a base repository pattern. Easily map class properties to Aerospike bins and perform CRUD operations

Features

• Decorators (@Bin) for defining Aerospike bins on class properties
• Base entity (BaseEntity) with automatic serialization/deserialization
• Base repository (BaseRepository) with CRUD, batch read, and query support
• Supports default values and required fields

Installation

npm i aerospike-orm

Usage example

import { BaseEntity, Bin, BaseRepository } from 'aerospike-orm'
import { AerospikeBins, Client as AerospikeClient, exp } from 'aerospike'

class User extends BaseEntity {
  @Bin('username', { required: true })
  public name!: string

  @Bin()
  public email?: string

  @Bin('age', { default: 18 })
  public age?: number
}

class UserRepository extends BaseRepository<User> {
  protected instantiate(bins: AerospikeBins): User {
    return User.fromRecord(bins)
  }
}

const client = new AerospikeClient({ hosts: '127.0.0.1:3000' })

async function main() {
  await client.connect()

  const repo = new UserRepository(client, 'test', 'users')

  // Create or get user
  const user = await repo.getOrCreate('user1', { name: 'Cool Name' })

  // Update
  await repo.update(user.id, { age: 25, email: '[email protected]' })

  // Fetch
  const fetched = await repo.get('user1')

  // Create user entity and save
  const extraUser = new User('user2')
  extraUser.name = 'Coolest'
  await repo.save(extraUser)

  // Get all users
  const allUsers = await repo.getAll()

  // Get users with stream filter (expression)
  const coolestNameUsers = await repo.getAll({
    stream: {
      filterExpression: exp.eq(exp.binStr('username'), exp.str('Coolest'))
    }
  })

  // Delete
  await repo.deleteMany([ 'user1', extraUser.id ])
}

main().catch(console.error).finally(() => client.close())

Methods

BaseEntity

| Property | Type | Description | |----------|--------------------|---------------------------------------------------------------------------------------------| | id | string \| number | A unique identifier for the entity (used as Aerospike record key). Required in all entities |

| Method | Description | |----------------------------------------------------------------------------------------|----------------------------------------------------------| | toRecord(): AerospikeBins | Serializes the entity to an Aerospike record (bins) | | static fromRecord<T extends typeof BaseEntity>(bins: AerospikeBins): InstanceType<T> | Deserializes an Aerospike record into an entity instance |

BaseRepository<T extends BaseEntity>

| Method | Description | |--------------------------------------------------------------------|--------------------------------------------------------------------| | save(entity: T): Promise<void> | Saves (inserts or updates) an entity | | get(id: string \| number): Promise<T \| null> | Retrieves an entity by ID. Returns null if not found | | getOrCreate(id: string \| number, data?: Partial<T>): Promise<T> | Retrieves an entity by ID or creates it with optional default data | | getMany(ids: (string \| number)[]): Promise<T[]> | Retrieves multiple entities by their IDs using batchRead | | getAll(options?: GetAllOptions): Promise<T[]> | Retrieves all entities, optionally with query/stream options | | exists(id: string \| number): Promise<boolean> | Checks if a record exists | | update(id: string \| number, data: Partial<T>): Promise<void> | Partially updates a record, modifying only the provided fields | | delete(id: string \| number): Promise<void> | Deletes an entity by ID | | deleteMany(ids: (string \| number)[]): Promise<void> | Delete multiple entities by their IDs using batchRemove |

GetAllOptions

Interface used by the getAll() method to control query behavior

export interface GetAllOptions {
  query?: Aerospike.QueryOptions
  stream?: Aerospike.QueryPolicy
}

Decorators

@Bin(name?: string, options?: BinOptions)

BinOptions

| Property | Type | Default | Description | |------------|--------------------------------------------------------------------|-------------|-----------------------------------------------------------------------| | required | boolean | false | If true, throws an error when the property is missing before saving | | default | Aerospike.AerospikeBinValue \| () => Aerospike.AerospikeBinValue | undefined | Default value assigned when the property is undefined |