@astralibx/core

Shared foundation for all @astralibx packages -- base errors, types, and validation helpers.

Install

npm install @astralibx/core

zod is included as a dependency -- no need to install it separately.

Quick Start

import { z } from 'zod';
import {
  AlxError,
  createConfigValidator,
  baseDbSchema,
  loggerSchema,
} from '@astralibx/core';

// 1. Extend AlxError for your package
class QueueError extends AlxError {
  constructor(message: string) {
    super(message, 'QUEUE_ERROR');
    this.name = 'QueueError';
  }
}

// 2. Compose a config schema from core fragments + your own fields
const queueConfigSchema = z.object({
  db: baseDbSchema,
  logger: loggerSchema.optional(),
  concurrency: z.number().int().positive().default(5),
});

// 3. Validate config -- throws ConfigValidationError on invalid input
const validate = createConfigValidator(queueConfigSchema);

validate({
  db: { connection: mongoClient.db() },
  concurrency: 10,
});

What's Included

Error classes

• AlxError -- Base error for the ecosystem. Carries a code string.
• ConfigValidationError -- Thrown on invalid config. Adds a field property.

Type contracts

• LogAdapter -- Logger-agnostic interface (info, warn, error methods).
• BaseDbConfig -- Database connection + optional collectionPrefix.
• BaseRedisConfig -- Redis connection + optional keyPrefix.

Zod schemas

• loggerSchema -- Validates a LogAdapter-shaped object.
• baseDbSchema -- Validates BaseDbConfig (connection must be non-null).
• baseRedisSchema -- Validates BaseRedisConfig (connection must be non-null).

Shared utilities

• noopLogger -- No-op LogAdapter for fallback when consumer doesn't provide a logger.
• RedisLock -- Distributed lock using Redis SET NX PX with safe Lua release.
• getParam(req, name) -- Extract route param from Express request.
• getQueryString(req, name) -- Extract query string param from Express request.
• sendSuccess(res, data, status?) -- Send { success: true, data } JSON response.
• sendError(res, error, status?) -- Send { success: false, error } JSON response.

Helpers

• createConfigValidator -- Takes a Zod schema, returns a validate function that throws ConfigValidationError on failure.

Documentation

• Error Classes -- AlxError, ConfigValidationError, extending for your package
• Type Contracts -- LogAdapter, BaseDbConfig, BaseRedisConfig
• Validation -- Zod schemas, createConfigValidator, composing schemas
• Package Author Guide -- Building new @astralibx packages on top of core

License

MIT