Project Title

Aerospike orm that make easy to use aerospike db for all developers , let you use most operation of common databaes with udf power;

NestJS Aerospike ORM

A fully-featured Aerospike ORM (Actually ODM) module for NestJS, providing convenient services to:

• Interact with Aerospike clusters
• Create secondary indexes
• Perform scans and queries
• Apply filtering, sorting, aggregation, and pagination
• Handle nested objects and arrays
• Manage TTL (default ttl is infinty that let you persist data), durable deletes, and upserts
• Automatically register UDF scripts

Works with TypeScript, NestJS, and both Community Edition (CE) and Enterprise Edition (EE) of Aerospike.

Table of Contents

• Installation
• Environment Variables
• Usage
• Service Methods
• Enums
• Utilities
• UDF Scripts
• Examples
• Contributing
• License

Installation

npm install @sawmaxxx/aerospike-orm
# or using yarn
yarn add @sawmaxxx/aerospike-orm

Environment Variables

AEROSPIKE_HOST=127.0.0.1:3000
AEROSPIKE_NAME_SPACE=test
AERO_VERSION_TYPE=ce # or ee for enterprise edition
AEROSPIKE_MAX_CONNECTION=300

Usage

Import the Module

import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { AerospikeModule } from "@sawmaxxx/aerospike-orm";

import { ConfigModule } from "@nestjs/config";
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: [".env"],
      cache: true,
    }),
    AerospikeModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Inject the Service

import { Injectable } from "@nestjs/common";
import { AerospikeService } from "@sawmaxxx/aerospike-orm";

@Injectable()
export class UserService {
  constructor(private readonly aerospikeService: AerospikeService) {}

  async getUser(userId: string) {
    return this.aerospikeService.get("users", userId);
  }

  async createUser(user: any) {
    return this.aerospikeService.put("users", user, user.id, {
      generateTimeStamps: true,
    });
  }
}

Service Methods

| Method | Description | | ------------------------------------------------------------------------------ | -------------------------------------- | | get<T>(set: string, key: string): Promise<T> | Retrieve a record by key | | put<T>(set: string, inputBin: Partial<T>, key: string, options?): Promise<T> | Upsert a record | | delete<T>(set: string, key: string, durableDelete?: boolean) | Delete a record | | getAll<T>(set: string, options?): Promise<{results: T[], total?: number}> | Retrieve multiple records with filters | | createSecondaryIndex<T>(params): Promise<void> | Create secondary index | | operateWithSingleKey<T>(set: string, key: string, operations: any[]) | Perform operations on a key | | countAll(set: string, filters, options, filterProccessType) | Count records in a set |

Enums

• IndexDataTypes - BLOB, STRING, INTEGER, GEO2DSPHERE, OBJECT
• IndexTypes - DEFAULT, LIST, MAPKEYS, MAPVALUES
• FilterOperations - EQUAL, RANGE, CONTAINS, LIKE, EQUAL_MAP_VALUE, CONTAINS_ARRAY, CONTAINS_MAP_VALUE
• RecordExistsActions - IGNORE, CREATE, UPDATE, REPLACE, CREATE_OR_REPLACE
• AggreagteOperations - SUM, COUNT, AVG, MAX, MIN
• SortTypes - ASC, DESC

Utilities

• generateObjectId() - Generates unique ObjectId
• aerospikeWhereChecker(where, record) - Checks if a record satisfies a where condition

UDF Scripts

• filter_query.lua - Used for complex query filtering
• order_by_query.lua - Used for ordering results

UDFs are automatically registered on module initialization.

Examples

// Get all records sorted by createdAt descending
const users = await this.aerospikeService.getAll<UserModel>("users", {
  sort: { binName: "createdAt", type: SortTypes.DESC },
  filterType: "and",
  pageIndex: 10,
  pageNumber: 1,
  returnTotal: true,
  //just use excludeBins option if that actually needed , its a bit make bad effect on speed also on high page index
  excludeBins: {
    bins: [
      "age",
    ]
  },

  skipSorting: false,
  secondaryIndexOption: { indexes : [
    {
       binName: "name",
       indexType: IndexTypes.DEFAULT,
       value: "john"
       filterOperation: FilterOperations.EQUAL ,
   }
  ]
  },
});

// Upsert a key
await this.aerospikeService.put<UserModel>("users", { name: "John Doe" }, "user_123", {
  generateTimeStamps: true,
  returnDoc: true,
  generateIdForArrayKeys: false,
  writePolicy: { exists: RecordExistsActions.IGNORE },
});

// Create secondary index
await this.aerospikeService.createSecondaryIndex({
  set: "users",
  binName: "name",
  indexDataType: IndexDataTypes.STRING,
  indexType: IndexTypes.DEFAULT,
  indexName: "users_index_name:v:1.1",
});

//Operate with single key (atomic operation)
await this.aerospikeService.operateWithSingleKey(
  "users",
  "user_123",
  [
    _aerospike.default.lists.append("profiles", {
      "user_123",
      meta: {
        bin: {name : "example"}
      },
    }),
  ],
  [
    //another op
  ]
);

//Aggreagte operations
 const userAnalytics = await this.aerospikeService.getAll<UserModel>(
      "users",
      {
        pageIndex: 100
        pageNumber: 1,
        returnTotal: false,
        hybridFilter: false,
        skipSorting: false,
        secondaryIndexOption: { indexes },
        groupBy: {
          groupByBinName: "eventName",
          aggregateBinName: "_id",
          aggreateOperation: AggreagteOperations.COUNT,
        },
      }
);

// Delete a key
await this.aerospikeService.delete("users", "user_123");

Contributing

1. Fork the repository
2. Create a branch (git checkout -b feature-name)
3. Make your changes
4. Submit a pull request

License

This project is licensed under the AGPL-3.0 License.