Utilities Reference

import {
  // Environment
  env,
  
  // Logger
  getLogger,
  initializeLogger,
  getOriginalConsole,
  
  // Database
  initializeDatabase,
  getDatabase,
  getSqlClient,
  testConnection,
  closeDatabase,
  
  // Cache
  getCacheService,
  initializeCacheService,
  closeCacheService,
  invalidateCollection,
  invalidateEntireCache,
  
  // Schema
  schemaManager,
  systemSchemas,
  
  // Query building
  drizzleWhere,
  drizzleOrder,
  combineFilters,
  applyPagination,
  applyFullTextSearch,
  
  // Utilities
  spatialUtils,
  fieldUtils,
  importUtils,
  schemaValidator,
  seedUtility,
  
  // Sorting
  sortItems,
  reorderItems,
  getNextSortValue,
  
  // Error handling
  APIError,
  errorHandler,
  
  // Type mapping
  mapJsonTypeToDrizzle,
  typeMapper,
  
  // Relations
  relationBuilder,
  RelationBuilder,
  
  // Workflow
  checkWorkflowRoleAccess,
  validateWorkflowAccess,
  
  // Custom types
  point,
  arrayText,
  rangeInteger,
  
  // Soft delete
  withSoftDelete,
  SoftDeleteHelper,
  
  // Auth
  createAuth,
  google,
  facebook,
  apple,
  github,
} from '@tspvivek/baasix';

env.get(key: string, defaultValue?: string): string | undefined

const port = env.get('PORT', '3000');
const dbUrl = env.get('DATABASE_URL');

env.require(key: string): string

const secretKey = env.require('SECRET_KEY'); // Throws if not set

env.getBoolean(key: string, defaultValue?: boolean): boolean

const isDebug = env.getBoolean('DEBUG', false);
const isMultiTenant = env.getBoolean('MULTI_TENANT');

env.getNumber(key: string, defaultValue?: number): number | undefined

const maxFileSize = env.getNumber('MAX_FILE_SIZE', 52428800);
const poolSize = env.getNumber('DB_POOL_SIZE', 10);

env.set(key: string, value: string): void

import { startServer } from "@tspvivek/baasix";

// Basic usage - pretty printing in dev, JSON in production
startServer();

// With custom logger options
startServer({
  port: 8056,
  logger: {
    level: "info",        // Log level
    pretty: true,         // Human-readable output
  }
});

import { getLogger } from "@tspvivek/baasix";

const logger = getLogger();

logger.info("Server started");
logger.error({ err: error }, "Failed to process request");
logger.debug({ userId, action }, "User action logged");

import { initializeLogger } from "@tspvivek/baasix";

const logger = initializeLogger({
  level: "debug",
  pretty: true
});

startServer({
  logger: {
    transport: {
      target: "pino/file",
      options: { destination: "./logs/app.log" }
    }
  }
});

startServer({
  logger: {
    transport: {
      targets: [
        { target: "pino-pretty", options: { colorize: true }, level: "info" },
        { target: "pino/file", options: { destination: "./logs/error.log" }, level: "error" }
      ]
    }
  }
});

npm install pino-datadog-transport

startServer({
  logger: {
    transport: {
      target: "pino-datadog-transport",
      options: {
        apiKey: process.env.DD_API_KEY,
        service: "baasix-api",
        env: process.env.NODE_ENV,
        ddsource: "nodejs"
      }
    }
  }
});

npm install pino-loki

startServer({
  logger: {
    transport: {
      target: "pino-loki",
      options: {
        host: "http://localhost:3100",
        labels: { application: "baasix-api", environment: "production" }
      }
    }
  }
});

npm install pino-elasticsearch

startServer({
  logger: {
    transport: {
      target: "pino-elasticsearch",
      options: {
        node: "http://localhost:9200",
        index: "baasix-logs",
        esVersion: 8
      }
    }
  }
});

function initializeDatabase(): Database

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

// Called automatically by Baasix, but can be used manually
const db = initializeDatabase();

function getDatabase(): Database

import { getDatabase } from '@tspvivek/baasix';
import { eq } from 'drizzle-orm';

const db = getDatabase();

// Use Drizzle ORM queries
const users = await db.select().from(usersTable).where(eq(usersTable.status, 'active'));

function getSqlClient(): PostgresClient

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

const sql = getSqlClient();

// Raw SQL query
const result = await sql`SELECT COUNT(*) FROM users WHERE status = 'active'`;

async function testConnection(): Promise<boolean>

async function closeDatabase(): Promise<void>

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

const db = getDatabase();

await db.transaction(async (tx) => {
  // All operations in this callback are in a transaction
  await tx.insert(ordersTable).values({ ... });
  await tx.insert(orderItemsTable).values({ ... });
  
  // Transaction automatically commits on success
  // or rolls back on error
});

function getCacheService(): CacheService | null

async function initializeCacheService(): Promise<CacheService>

async function closeCacheService(): Promise<void>

async function invalidateCollection(collection: string): Promise<void>

async function invalidateEntireCache(): Promise<void>

const cache = getCacheService();

// Get a cached value
const value = await cache.get('my-key');

// Set a cached value (TTL in seconds)
await cache.set('my-key', { data: 'value' }, 3600);

// Delete a cached value
await cache.delete('my-key');

// Invalidate by pattern
await cache.invalidateByPattern('user:*');

// Invalidate by tables (used internally)
await cache.invalidateByTables(['posts', 'comments']);

// Get cache stats
const stats = await cache.getStats();
console.log(`Keys: ${stats.keys}, Size: ${stats.size}`);

# Enable caching
CACHE_ENABLED=true

# Cache adapter: memory, redis, upstash
CACHE_ADAPTER=redis

# Redis configuration
CACHE_REDIS_URL=redis://localhost:6379

# Upstash configuration
CACHE_UPSTASH_URL=https://your-url.upstash.io
CACHE_UPSTASH_TOKEN=your-token

# Default TTL in seconds
CACHE_TTL=3600

# In-memory cache size limit (GB)
CACHE_MAX_SIZE_GB=1

schemaManager.getTable(collection: string): PgTable

import { schemaManager, getDatabase } from '@tspvivek/baasix';
import { eq } from 'drizzle-orm';

const db = getDatabase();
const postsTable = schemaManager.getTable('posts');

const posts = await db.select().from(postsTable).where(eq(postsTable.status, 'published'));

schemaManager.getPrimaryKey(collection: string): string

schemaManager.getSchema(collection: string): SchemaDefinition

schemaManager.getRelation(collection: string, relationName: string): RelationDefinition

const relation = schemaManager.getRelation('posts', 'author');
// Returns: { type: 'BelongsTo', relatedCollection: 'users', foreignKey: 'author_Id' }

schemaManager.getRelationNames(collection: string): string[]

schemaManager.isParanoid(collection: string): boolean

schemaManager.hasField(collection: string, fieldName: string): boolean

schemaManager.getFieldDefinition(collection: string, fieldName: string): FieldDefinition

function drizzleWhere(
  filter: FilterObject,
  options: {
    table: PgTable;
    tableName: string;
    schema?: any;
    joins?: any[];
  }
): SQL | undefined

import { drizzleWhere, schemaManager, getDatabase } from '@tspvivek/baasix';

const db = getDatabase();
const table = schemaManager.getTable('posts');

const whereClause = drizzleWhere({
  status: { eq: 'published' },
  createdAt: { gte: '2024-01-01' },
  OR: [
    { category: 'tech' },
    { category: 'science' }
  ]
}, {
  table,
  tableName: 'posts'
});

const posts = await db.select().from(table).where(whereClause);

function drizzleOrder(
  sort: string | string[] | Record<string, 'asc' | 'desc'>,
  options: { table: PgTable; tableName: string }
): SQL[]

import { drizzleOrder, schemaManager } from '@tspvivek/baasix';

const table = schemaManager.getTable('posts');

// Array format
const orderBy1 = drizzleOrder(['-createdAt', 'title'], { table, tableName: 'posts' });

// Object format
const orderBy2 = drizzleOrder({ createdAt: 'desc', title: 'asc' }, { table, tableName: 'posts' });

function combineFilters(...filters: FilterObject[]): FilterObject

const baseFilter = { status: 'active' };
const searchFilter = { title: { contains: 'search' } };
const tenantFilter = { tenant_Id: 'tenant-123' };

const combined = combineFilters(baseFilter, searchFilter, tenantFilter);

function applyPagination(options: {
  limit?: number;
  page?: number;
  offset?: number;
}): { limit?: number; offset?: number }

const { limit, offset } = applyPagination({ page: 2, limit: 10 });
// Returns: { limit: 10, offset: 10 }

function applyFullTextSearch(
  collection: string,
  table: PgTable,
  searchQuery: string,
  searchFields?: string[],
  sortByRelevance?: boolean
): { searchCondition: SQL; orderClause?: SQL }

spatialUtils.createPoint(lat: number, lng: number): SQL

spatialUtils.createPolygon(coordinates: [number, number][]): SQL

spatialUtils.withinRadius(
  column: string,
  lat: number,
  lng: number,
  radiusMeters: number
): SQL

import { spatialUtils, schemaManager, getDatabase } from '@tspvivek/baasix';

const db = getDatabase();
const storesTable = schemaManager.getTable('stores');

// Find stores within 5km of a location
const nearbyStores = await db
  .select()
  .from(storesTable)
  .where(spatialUtils.withinRadius('location', 40.7128, -74.0060, 5000));

spatialUtils.calculateDistance(
  column: string,
  lat: number,
  lng: number
): SQL

spatialUtils.intersects(column: string, geometry: SQL): SQL

fieldUtils.validateFieldValue(
  value: any,
  fieldDef: FieldDefinition
): { valid: boolean; error?: string }

fieldUtils.coerceFieldValue(
  value: any,
  fieldType: string
): any

fieldUtils.getDefaultValue(fieldDef: FieldDefinition): any

async importUtils.importFromCSV(
  collection: string,
  filePath: string,
  options?: ImportOptions
): Promise<ImportResult>

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

const result = await importUtils.importFromCSV('products', './import/products.csv', {
  mapping: {
    'Product Name': 'name',
    'Price USD': 'price',
    'Category': 'category_Id'
  },
  onError: 'skip'
});

console.log(`Imported: ${result.success}, Failed: ${result.failed}`);

async importUtils.importFromJSON(
  collection: string,
  filePath: string,
  options?: ImportOptions
): Promise<ImportResult>

async importUtils.exportToCSV(
  collection: string,
  filePath: string,
  query?: QueryOptions
): Promise<number>

schemaValidator.validateSchema(schema: SchemaDefinition): ValidationResult

schemaValidator.validateField(field: FieldDefinition): ValidationResult

schemaValidator.validateRelation(relation: RelationDefinition): ValidationResult

async seedUtility.seedCollection(
  collection: string,
  data: any[],
  options?: SeedOptions
): Promise<SeedResult>

async seedUtility.seedMultiple(
  seeds: SeedConfig[]
): Promise<SeedResult[]>

seedUtility.generateTemplate(collection: string): object

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

// Seed with sample data
await seedUtility.seedCollection('categories', [
  { name: 'Electronics', slug: 'electronics' },
  { name: 'Clothing', slug: 'clothing' },
  { name: 'Books', slug: 'books' }
], { truncate: true });

// Seed multiple collections in order
await seedUtility.seedMultiple([
  {
    collection: 'categories',
    data: categoriesData,
    truncate: true
  },
  {
    collection: 'products',
    data: productsData,
    truncate: true
  }
]);

async checkWorkflowRoleAccess(
  workflowId: string | number,
  roleId: string | number
): Promise<boolean>

async validateWorkflowAccess(
  workflowId: string | number,
  accountability: any
): Promise<{ hasAccess: boolean; reason?: string }>

async fetchAndValidateWorkflow(
  workflowId: string | number,
  accountability: any
): Promise<{ workflow: Workflow; hasAccess: boolean }>

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

// In a custom endpoint
app.post('/run-workflow/:id', async (req, res) => {
  const { hasAccess, reason } = await validateWorkflowAccess(
    req.params.id,
    req.accountability
  );
  
  if (!hasAccess) {
    return res.status(403).json({ error: reason });
  }
  
  // Execute workflow...
});

async sortItems(options: SortOptions): Promise<SortResult>

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

// Move task 'abc' before task 'xyz'
const result = await sortItems({
  collection: 'tasks',
  item: 'abc',
  to: 'xyz',
  accountability: req.accountability
});

console.log(`Moved item to sort position: ${result.newSort}`);

async reorderItems(options: {
  collection: string;
  items: (string | number)[];
  accountability?: any;
  bypassPermissions?: boolean;
}): Promise<void>

async getNextSortValue(
  collection: string
): Promise<number>

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

const nextSort = await getNextSortValue('tasks');
// Use when creating a new item to place it at the end

class APIError extends Error {
  statusCode: number;
  isOperational: boolean;
  details: any;
  
  constructor(
    message: string, 
    statusCode?: number, 
    details?: any
  )
}

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

// Throw a 404 error
throw new APIError('Resource not found', 404);

// Throw a 400 error with details
throw new APIError('Validation failed', 400, {
  field: 'email',
  message: 'Invalid email format'
});

// Throw a 403 error
throw new APIError('Permission denied', 403);

function errorHandler(
  error: Error | APIError,
  req: Request,
  res: Response,
  next: NextFunction
): void

import express from 'express';
import { errorHandler, APIError } from '@tspvivek/baasix';

const app = express();

// Your routes
app.get('/api/resource/:id', async (req, res, next) => {
  try {
    const resource = await findResource(req.params.id);
    if (!resource) {
      throw new APIError('Resource not found', 404);
    }
    res.json(resource);
  } catch (error) {
    next(error);
  }
});

// Error handler middleware (should be last)
app.use(errorHandler);

function mapJsonTypeToDrizzle(
  fieldName: string,
  fieldSchema: FieldSchema
): any

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

const column = mapJsonTypeToDrizzle('email', {
  type: 'String',
  values: { stringLength: 100 },
  allowNull: false
});

import { relationBuilder, RelationBuilder } from '@tspvivek/baasix';

relationBuilder.storeAssociations(
  tableName: string,
  associations: Record<string, AssociationDefinition>
): void

relationBuilder.getAssociations(
  tableName: string
): Record<string, AssociationDefinition> | undefined

relationBuilder.getForeignKey(
  assoc: AssociationDefinition,
  defaultKey?: string
): string

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

// Get relations for a table
const postAssociations = relationBuilder.getAssociations('posts');

// Check if it's a one-to-many relation
if (relationBuilder.isOneToMany(postAssociations.comments)) {
  console.log('Posts have many comments');
}

// Get foreign key
const fk = relationBuilder.getForeignKey(
  postAssociations.author,
  'authorId'
);

function createForeignKeySQL(
  tableName: string,
  columnName: string,
  referencedTable: string,
  referencedColumn?: string,
  onDelete?: string,
  onUpdate?: string
): string

function isPolymorphicRelation(
  assoc: AssociationDefinition
): boolean

function getPolymorphicFields(
  relationName: string
): { typeField: string; idField: string }

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

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

// Get all system schema definitions
const schemas = systemSchemas.schemas;

// Find a specific schema
const userSchema = schemas.find(
  s => s.collectionName === 'baasix_User'
);

console.log(userSchema.schema.fields);

import {
  point,
  lineString,
  polygon,
  multiPoint,
  multiLineString,
  multiPolygon,
  geometryCollection,
  geography,
  geometry
} from '@tspvivek/baasix';

import {
  arrayInteger,
  arrayBigInt,
  arrayText,
  arrayVarchar,
  arrayUuid,
  arrayBoolean,
  arrayDecimal,
  arrayDouble,
  arrayDate,
  arrayDateTime,
  arrayDateTimeTz,
  arrayDateOnly,
  arrayTime,
  arrayTimeTz,
  arrayOf
} from '@tspvivek/baasix';

import {
  rangeInteger,
  rangeBigInt,
  rangeDecimal,
  rangeDate,
  rangeDateTime,
  rangeDateTimeTz,
  rangeDouble,
  rangeTime,
  rangeTimeTz,
  type Range
} from '@tspvivek/baasix';

import { point, arrayText, rangeInteger } from '@tspvivek/baasix';
import { pgTable, uuid, varchar } from 'drizzle-orm/pg-core';

// Using custom types in a schema
const locations = pgTable('locations', {
  id: uuid('id').primaryKey(),
  name: varchar('name', { length: 255 }),
  coordinates: point('coordinates'),      // PostGIS point
  tags: arrayText('tags'),                 // TEXT[]
  priceRange: rangeInteger('price_range') // int4range
});

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

function withSoftDelete<T>(
  tableName: string,
  columns: T,
  options?: SoftDeleteOptions
): T & SoftDeleteMixin

import { withSoftDelete } from '@tspvivek/baasix';
import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';

const posts = pgTable('posts', withSoftDelete('posts', {
  id: uuid('id').primaryKey(),
  title: varchar('title', { length: 255 }),
  createdAt: timestamp('createdAt').defaultNow()
}));

// The table now has a deletedAt column

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

const softDelete = new SoftDeleteHelper('deletedAt');

softDelete.excludeDeleted(table): SQL

softDelete.onlyDeleted(table): SQL

softDelete.markAsDeleted(): Date

softDelete.markAsRestored(): null

import { SoftDeleteHelper } from '@tspvivek/baasix';
import { and } from 'drizzle-orm';

const softDelete = new SoftDeleteHelper();

// Query excluding soft-deleted records
const activePosts = await db
  .select()
  .from(posts)
  .where(and(
    eq(posts.status, 'published'),
    softDelete.excludeDeleted(posts)
  ));

// Query only soft-deleted records
const deletedPosts = await db
  .select()
  .from(posts)
  .where(softDelete.onlyDeleted(posts));

// Soft delete a record
await db
  .update(posts)
  .set({ deletedAt: softDelete.markAsDeleted() })
  .where(eq(posts.id, postId));

// Restore a record
await db
  .update(posts)
  .set({ deletedAt: softDelete.markAsRestored() })
  .where(eq(posts.id, postId));

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

const auth = createAuth({
  secret: process.env.SECRET_KEY,
  emailAndPassword: { enabled: true },
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET
    }
  }
});

import {
  google,
  facebook,
  apple,
  github,
  credential
} from '@tspvivek/baasix';

import {
  createSessionService,
  createTokenService,
  createVerificationService,
  validateSessionLimits
} from '@tspvivek/baasix';

import {
  generateState,
  generateCodeVerifier,
  generateCodeChallenge,
  createAuthorizationURL,
  validateAuthorizationCode
} from '@tspvivek/baasix';