tessl/npm-medusa-interfaces

Core interfaces for Medusa e-commerce framework service implementations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Base Service

Name: tessl/npm-medusa-interfaces
Author: tessl

Core service functionality providing transaction management, query building, validation utilities, and decorator pattern support. All other service interfaces in medusa-interfaces extend this base class.

Deprecation Notice: Use TransactionBaseService from @medusajs/medusa instead.

Capabilities

Constructor

Creates a new BaseService instance with an empty decorators array.

/**
 * Creates a new BaseService instance
 */
constructor();

Transaction Management

Methods for managing database transactions and ensuring data consistency.

/**
 * Returns this instance - warns about missing custom implementation
 * @returns {BaseService} this instance
 */
withTransaction(): BaseService;

/**
 * Wraps work within a transactional block with optional isolation level and error handling
 * @param {function} work - The transactional work to be done
 * @param {string|function} isolationOrErrorHandler - Isolation level or error handler function
 * @param {function|boolean} maybeErrorHandlerOrDontFail - Error handler or don't fail flag
 * @returns {Promise<any>} Result of the transactional work
 */
atomicPhase_(
  work: function, 
  isolationOrErrorHandler?: string | function, 
  maybeErrorHandlerOrDontFail?: function | boolean
): Promise<any>;

/**
 * Determines if a transaction should be retried based on error code
 * @param {object} err - Error object to check
 * @returns {boolean} True if transaction should be retried
 */
shouldRetryTransaction(err: object): boolean;

Usage Example:

import { BaseService } from "medusa-interfaces";

class MyService extends BaseService {
  async performWork() {
    return await this.atomicPhase_(async (manager) => {
      // Database operations within transaction
      const result = await manager.save(entity);
      return result;
    });
  }
}

Query Building

Utility for building TypeORM queries with selectors and configuration.

/**
 * Used to build TypeORM queries
 * @param {object} selector - Query selector object
 * @param {object} config - Query configuration options
 * @returns {object} Built query object
 */
buildQuery_(selector: object, config?: object): object;

Validation

ID validation with optional configuration for prefix and length checking.

/**
 * Confirms whether a given raw id is valid
 * @param {string} rawId - The id to validate
 * @param {object} config - Optional config for prefix and length validation
 * @returns {string} The validated rawId
 * @throws {Error} If rawId is null or undefined
 */
validateId_(rawId: string, config?: object): string;

Metadata Management

Method for setting metadata on entities.

/**
 * Dedicated method to set metadata on an entity
 * @param {object} obj - The entity to apply metadata to
 * @param {object} metadata - The metadata to set
 * @returns {Promise<object>} Promise resolving to the updated result
 */
setMetadata_(obj: object, metadata: object): Promise<object>;

Decorator Pattern

Support for adding and running decorators to extend service functionality.

/**
 * Adds a decorator to a service - must be a function
 * @param {function} fn - The decorator function to add
 * @throws {Error} If fn is not a function
 */
addDecorator(fn: function): void;

/**
 * Runs all registered decorators on an object in registration order
 * @param {object} obj - The object to decorate
 * @param {array} fields - Fields array for decoration
 * @param {array} expandFields - Expand fields array for decoration  
 * @returns {Promise<object>} The decorated object
 */
runDecorators_(obj: object, fields?: array, expandFields?: array): Promise<object>;

Usage Example:

import { BaseService } from "medusa-interfaces";

class MyService extends BaseService {
  constructor() {
    super();
    
    // Add a decorator that adds timestamps
    this.addDecorator((obj) => ({
      ...obj,
      decorated_at: new Date().toISOString()
    }));
  }

  async processObject(obj) {
    // Run decorators on the object
    return await this.runDecorators_(obj);
  }
}

Properties

Instance Properties

/**
 * Array of decorator functions registered with addDecorator
 */
decorators_: function[];

/**
 * Current transaction manager instance
 */
manager_: object;

/**
 * Current transaction manager for atomic operations
 */
transactionManager_: object;