Services Reference

import {
  ItemsService,
  FilesService,
  AssetsService,
  MailService,
  NotificationService,
  StorageService,
  SettingsService,
  PermissionService,
  HooksManager,
  TasksService,
  WorkflowService,
  SocketService,
  ReportService,
  StatsService,
  getCacheService,
} from '@tspvivek/baasix';

new ItemsService(collection: string, params?: ServiceParams)

async readByQuery(
  query: QueryOptions,
  skipCount?: boolean
): Promise<ReadResult>

const itemsService = new ItemsService('posts', {
  accountability: req.accountability,
});

// Basic query with filter and sort
const result = await itemsService.readByQuery({
  filter: { status: { eq: 'published' } },
  fields: ['id', 'title', 'author.name', 'category.name'],
  sort: ['-createdAt'],
  limit: 10,
  page: 1,
});

// With search and relConditions (for HasMany relations like comments)
const searchResult = await itemsService.readByQuery({
  search: 'typescript',
  searchFields: ['title', 'content'],
  fields: ['*', 'comments.*'],
  relConditions: {
    comments: { isApproved: { eq: true } }, // Only load approved comments
  },
});

console.log(result.data); // Array of records
console.log(result.totalCount); // Total matching records

async readOne(
  id: string | number,
  query?: QueryOptions
): Promise<any>

const post = await itemsService.readOne('post-uuid', {
  fields: ['*', 'author.*', 'comments.*'],
});

async createOne(
  data: Record<string, any>,
  options?: OperationOptions
): Promise<string | number>

const postId = await itemsService.createOne({
  title: 'New Post',
  content: 'Post content...',
  status: 'draft',
  author_Id: req.accountability.user.id,
});

async createMany(
  data: Record<string, any>[],
  options?: OperationOptions
): Promise<(string | number)[]>

const ids = await itemsService.createMany([
  { title: 'Post 1', status: 'draft' },
  { title: 'Post 2', status: 'published' },
]);

async updateOne(
  id: string | number,
  data: Record<string, any>,
  options?: OperationOptions
): Promise<string | number>

await itemsService.updateOne('post-uuid', {
  title: 'Updated Title',
  status: 'published',
});

async updateMany(
  updates: { id: string | number; data?: Record<string, any>; [key: string]: any }[],
  options?: OperationOptions
): Promise<(string | number)[]>

// Update with individual data per item
const updatedIds = await itemsService.updateMany([
  { id: 'uuid-1', data: { status: 'published', priority: 1 } },
  { id: 'uuid-2', data: { status: 'draft', priority: 2 } },
]);

// Alternative: spread fields directly (without data wrapper)
const updatedIds = await itemsService.updateMany([
  { id: 'uuid-1', status: 'published', priority: 1 },
  { id: 'uuid-2', status: 'draft', priority: 2 },
]);

async updateByQuery(
  filter: object,
  data: Record<string, any>,
  options?: OperationOptions
): Promise<number>

const count = await itemsService.updateByQuery(
  { status: { eq: 'draft' }, createdAt: { lt: '2024-01-01' } },
  { status: 'archived' },
);

async deleteOne(
  id: string | number,
  options?: OperationOptions
): Promise<string | number>

async deleteMany(
  ids: (string | number)[],
  options?: OperationOptions
): Promise<(string | number)[]>

async softDelete(id: string | number): Promise<void>
async restore(id: string | number): Promise<void>

new FilesService(params?: { accountability?: any })

async createOne(
  fileData: { file: UploadedFile },
  metadata?: FileMetadata
): Promise<string | number>

const filesService = new FilesService({
  accountability: req.accountability,
});

const fileId = await filesService.createOne(
  { file: req.files.upload },
  {
    title: 'Profile Photo',
    storage: 'local',
    isPublic: true,
  },
);

async readOne(id: string | number): Promise<FileRecord>

async deleteOne(id: string | number): Promise<void>

async downloadFromUrl(
  url: string,
  metadata?: FileMetadata
): Promise<string | number>

async sendMail(options: MailOptions): Promise<any>

import { MailService } from '@tspvivek/baasix';

await MailService.sendMail({
  to: 'user@example.com',
  subject: 'Welcome to Our App',
  templateName: 'welcome',
  context: {
    userName: 'John',
    activationLink: 'https://app.example.com/activate/token123',
  },
});

<!-- extensions/baasix-templates/mails/welcome.liquid -->
<html>
  <body>
    <h1>Welcome, {{ userName }}!</h1>
    <p>Click below to activate your account:</p>
    <a href="{{ activationLink }}">Activate Account</a>
  </body>
</html>

new NotificationService(params?: { accountability?: any })

async send(options: NotificationOptions): Promise<(string | number)[]>

const notificationService = new NotificationService({
  accountability: req.accountability,
});

await notificationService.send({
  type: 'info',
  title: 'New Comment',
  message: 'Someone commented on your post',
  data: { postId: 'post-123' },
  userIds: ['user-1', 'user-2'],
});

async markAsSeen(
  userId: string,
  notificationIds?: string[] | null
): Promise<number>

async getUnreadCount(userId: string): Promise<number>

async getUserNotifications(query?: QueryOptions): Promise<ReadResult>

async deleteForUser(
  userId: string,
  notificationIds?: string[] | null
): Promise<number>

getProvider(service: string): StorageProvider

async saveFile(
  service: string,
  filePath: string,
  fileContent: Buffer
): Promise<string>

async getFile(service: string, filePath: string): Promise<Buffer>

async deleteFile(service: string, filePath: string): Promise<void>

async getPublicUrl(service: string, filePath: string): Promise<string>

import { StorageService } from '@tspvivek/baasix';

// Save a file
const filePath = await StorageService.saveFile('local', 'documents/report.pdf', fileBuffer);

// Get signed URL (for S3)
const url = await StorageService.getPublicUrl('s3', 'documents/report.pdf');

getGlobalSettings(): TenantSettings

async getTenantSettings(tenantId: string | number): Promise<TenantSettings>

async updateGlobalSettings(
  data: Partial<TenantSettings>,
  accountability?: any
): Promise<TenantSettings>

async updateTenantSettings(
  tenantId: string | number,
  data: Partial<TenantSettings>,
  accountability?: any
): Promise<TenantSettings>

import { SettingsService } from '@tspvivek/baasix';

// Get global settings
const settings = SettingsService.getGlobalSettings();
console.log(settings.project_name);

// Get tenant-specific settings (merged with global)
const tenantSettings = await SettingsService.getTenantSettings('tenant-123');

import { getCacheService } from '@tspvivek/baasix';

const cache = getCacheService();

async get(key: string): Promise<any | null>

async set(
  key: string,
  value: any,
  ttl?: number
): Promise<void>

async delete(key: string): Promise<void>

import { invalidateCollection } from '@tspvivek/baasix';

await invalidateCollection('posts');

import { invalidateEntireCache } from '@tspvivek/baasix';

await invalidateEntireCache();

const cache = getCacheService();

// Cache a computed value
await cache.set('dashboard:stats', computedStats, 3600); // 1 hour TTL

// Get cached value
const stats = await cache.get('dashboard:stats');

// Invalidate on data change
await invalidateCollection('orders');

registerHook(
  collection: string,
  event: string,
  hookFunction: HookFunction
): void

type HookFunction = (context: HookContext) => Promise<HookContext | void>;

interface HookContext {
  collection: string;
  accountability: any;
  db: Database;
  data?: Record<string, any>; // For create/update
  document?: Record<string, any>; // After operations
  id?: string | number; // For update/delete
  ids?: (string | number)[]; // For bulk operations
}

import { HooksManager } from '@tspvivek/baasix';

// Register in extensions/baasix-hook-posts/index.js
export default function (hooksManager, context) {
  // Before creating a post
  hooksManager.registerHook('posts', 'items.create.before', async (ctx) => {
    // Add slug from title
    if (ctx.data.title) {
      ctx.data.slug = ctx.data.title.toLowerCase().replace(/\s+/g, '-');
    }
    return ctx;
  });

  // After creating a post
  hooksManager.registerHook('posts', 'items.create.after', async (ctx) => {
    // Send notification
    console.log('Post created:', ctx.document.id);
  });

  // Wildcard hook for all collections
  hooksManager.registerHook('*', 'items.create.after', async (ctx) => {
    console.log(`Record created in ${ctx.collection}`);
  });
}

# Enable task service
TASK_SERVICE_ENABLED=true

# For multi-instance deployments
TASK_REDIS_ENABLED=true
TASK_REDIS_URL=redis://localhost:6379

async getNotStartedTasks(): Promise<Task[]>

async tryAcquireLock(lockTimeout?: number): Promise<boolean>

async releaseLock(): Promise<boolean>

async getCacheStats(): Promise<{
  cachedTasksCount: number;
  isTaskRunning: boolean;
  refreshInterval: number;
  initialized: boolean;
  distributedMode: boolean;  // true when TASK_REDIS_ENABLED
  instanceId: string;
}>

// extensions/baasix-schedule-task-processor/index.js
import { TasksService, ItemsService } from '@tspvivek/baasix';

const tasksService = new TasksService();

export default async function (hooksManager, context) {
  // Run every minute
  setInterval(async () => {
    // Try to acquire lock (only one instance processes)
    const hasLock = await tasksService.tryAcquireLock(60);
    if (!hasLock) return;

    try {
      const tasks = await tasksService.getNotStartedTasks();

      for (const task of tasks) {
        if (new Date(task.scheduled_time) <= new Date()) {
          // Process task
          await processTask(task);
        }
      }
    } finally {
      await tasksService.releaseLock();
    }
  }, 60000);
}

async executeWorkflow(
  workflowId: string | number,
  triggerData?: any,
  userId?: any,
  tenantId?: any
): Promise<WorkflowExecution>

registerCustomModule(
  moduleName: string,
  moduleExport: any,
  options?: { description?: string }
): void

import { WorkflowService } from '@tspvivek/baasix';

// Register custom module
WorkflowService.registerCustomModule(
  'myUtils',
  {
    formatCurrency: (amount) => `$${amount.toFixed(2)}`,
    calculateTax: (amount, rate) => amount * rate,
  },
  {
    description: 'Custom utility functions',
  },
);

// Execute workflow
const execution = await WorkflowService.executeWorkflow(
  'workflow-uuid',
  { orderId: 'order-123' },
  req.accountability.user.id,
);

broadcastChange(
  collection: string,
  action: 'create' | 'update' | 'delete',
  data: any,
  accountability?: any
): void

emitToUser(
  userId: string | number,
  event: string,
  data: any
): void

emitToTenant(
  tenantId: string | number,
  event: string,
  data: any
): void

import { SocketService } from '@tspvivek/baasix';

// Broadcast custom event
SocketService.emitToUser('user-123', 'order:shipped', {
  orderId: 'order-456',
  trackingNumber: 'TRACK123',
});

// Broadcast to tenant
SocketService.emitToTenant('tenant-789', 'announcement', {
  message: 'System maintenance scheduled',
});

new ReportService(
  collection: string,
  params?: { accountability?: any }
)

async generateReport(query: ReportQuery): Promise<ReadResult>

const reportService = new ReportService('orders', {
  accountability: req.accountability,
});

const report = await reportService.generateReport({
  fields: ['status', 'customer.name'],
  filter: { createdAt: { gte: '2024-01-01' } },
  aggregate: {
    count: '*',
    sum: ['total'],
    avg: ['total'],
  },
  groupBy: ['status'],
});

new StatsService(params?: { accountability?: any })

async generateStats(queries: StatsQuery[]): Promise<StatsResult>

const statsService = new StatsService({
  accountability: req.accountability,
});

const stats = await statsService.generateStats([
  {
    name: 'totalOrders',
    collection: 'orders',
    query: { aggregate: { count: '*' } },
  },
  {
    name: 'revenueByMonth',
    collection: 'orders',
    query: {
      fields: ['createdAt'],
      aggregate: { sum: ['total'] },
      groupBy: ['month(createdAt)'],
    },
  },
  {
    name: 'topProducts',
    collection: 'order_items',
    query: {
      fields: ['product.name'],
      aggregate: { sum: ['quantity'] },
      groupBy: ['product_Id'],
      sort: ['-sum_quantity'],
      limit: 10,
    },
  },
]);

console.log(stats.data.totalOrders);
console.log(stats.data.revenueByMonth);
console.log(stats.data.topProducts);

new AssetsService(params?: { accountability?: any })

async getAsset(
  id: string | number,
  query: AssetQuery,
  bypassPermissions?: boolean
): Promise<AssetResult>

import { AssetsService } from '@tspvivek/baasix';

const assetsService = new AssetsService({
  accountability: req.accountability,
});

// Get resized image
const asset = await assetsService.getAsset('file-uuid', {
  width: 300,
  height: 300,
  fit: 'cover',
  quality: 80,
});

// Set response headers
res.setHeader('Content-Type', asset.contentType);
res.send(asset.buffer);

async processImage(
  filePath: string,
  options: AssetQuery
): Promise<ProcessedImage>

const processed = await assetsService.processImage('/path/to/image.jpg', {
  width: 800,
  height: 600,
  fit: 'contain',
  quality: 85,
});

// processed.buffer contains the transformed image
// processed.contentType is 'image/jpeg'

async deleteProcessedVersions(file: any): Promise<void>

async canAccess(
  roleId: string | number,
  collection: string,
  action: string,
  fields?: string[]
): Promise<boolean>

import PermissionService from '@tspvivek/baasix';

const hasAccess = await PermissionService.canAccess(roleId, 'posts', 'update', ['title', 'content']);

if (!hasAccess) {
  throw new APIError('Permission denied', 403);
}

async getPermissions(roleId: string | number): Promise<Permission[]>

async getCollectionPermissions(
  roleId: string | number,
  collection: string
): Promise<Permission[]>