Atma.js IO Middleware Base

1.0.51 verified Thu Apr 23 auth: no javascript abandoned

This package, `atma-io-middleware-base` (current stable version 1.0.51), serves as a foundational utility for abstracting and creating custom middleware extensions for the `atma-io` library. It simplifies the process of integrating custom file processing logic—such as reading, compiling, or preprocessing files—into the `atma-io` ecosystem. Developers use it to define synchronous `process` or asynchronous `processAsync` methods that transform file content, returning an object with the modified content and an optional source map. Its configuration can be extended via `package.json` under the specific middleware's name. As part of the Atma.js Project, this package's development appears to be inactive, with the last known activity dating back to 2017, suggesting an abandoned or unmaintained status.

Common errors

error Error: Cannot find module 'atma-io' or Missing peer dependency 'atma-io' ↓

cause The `atma-io` package is a peer dependency and must be explicitly installed alongside `atma-io-middleware-base`.

fix

Install the peer dependency: npm install atma-io or yarn add atma-io.

error TypeError: create is not a function ↓

cause This usually indicates an incorrect import statement. The package exports `create` as a named export, not a default export.

fix

Use a named import: import { create } from 'atma-io-middleware-base'; or for CommonJS: const { create } = require('atma-io-middleware-base');

error Argument of type '{ name: string; process(...): { content: string; }; }' is not assignable to parameter of type 'IFileMiddleware<any>' ↓

cause This TypeScript error often occurs when the `process` or `processAsync` method's return type or parameters don't exactly match the `IFileMiddleware` interface expected by `create`.

fix

Ensure that process and processAsync methods return an object with at least a content: string property, and optionally sourceMap: string. Also, correctly type your options generic parameter if used.

Warnings

breaking The package `atma-io-middleware-base` appears to be abandoned, with no significant updates or commits since 2017. This implies potential compatibility issues with newer Node.js versions, updated TypeScript features, or recent versions of its peer dependency `atma-io`. ↓

fix Consider migrating to actively maintained alternatives if available within the Atma.js ecosystem, or fork the repository to apply necessary updates and security patches.

gotcha The package's primary export method `create` is designed for use with `atma-io` version `>=1.1.7`. Using older versions of `atma-io` may lead to unexpected behavior, missing features, or runtime errors as the API contracts might have evolved. ↓

fix Ensure `atma-io` is installed and meets the peer dependency requirement (npm i atma-io@^1.1.7).

gotcha While the package ships TypeScript types, its age (last updated 2017) means the types might not fully align with modern TypeScript strictness or newer language features. Manual type assertions or stricter linting might be required. ↓

fix Review generated types for compatibility with your project's TypeScript configuration and consider adding custom declaration files (`.d.ts`) if necessary for stricter typing or newer features.

gotcha The README and examples primarily demonstrate CommonJS `require()`. In modern Node.js environments configured for ESM, attempting to `require()` this package directly might result in `ERR_REQUIRE_ESM` or `create is not a function` errors if the package is not transpiled or handled correctly. ↓

fix Prefer `import { create } from 'atma-io-middleware-base';` in ESM projects. If using CJS in an ESM-dominant project, ensure proper interoperability or transpilation. For older Node.js versions, `const { create } = require('atma-io-middleware-base');` is correct.

Install

npm install atma-io-middleware-base

yarn add atma-io-middleware-base

pnpm add atma-io-middleware-base

Imports

create
wrong
```
const { create } = require('atma-io-middleware-base');
```
correct
```
import { create } from 'atma-io-middleware-base';
```
While the README shows CommonJS `require`, modern Node.js and TypeScript projects should use ESM `import`. This package primarily provided CJS exports based on its last update in 2017.
MiddlewareConfig
```
import type { MiddlewareConfig } from 'atma-io-middleware-base';
```
This package ships TypeScript types, allowing for type-safe definition of middleware configuration objects, including `name`, `process`, and `processAsync` methods.

Quickstart

This quickstart demonstrates how to create a custom `atma-io` file middleware using `create`, defining both synchronous and asynchronous `process` methods, and showing its basic structure and conceptual usage.

import { create } from 'atma-io-middleware-base';
import { File, type IFileMiddleware } from 'atma-io'; // Peer dependency

interface MyCustomOptions {
  prefix?: string;
}

// Define the middleware configuration
const myMiddleware: IFileMiddleware<MyCustomOptions> = create<MyCustomOptions>({
  name: 'my-super-middleware',
  // Synchronous processing example
  process(content, filename, options) {
    const prefixedContent = options.prefix ? `${options.prefix}: ${content}` : content;
    console.log(`Processing sync file: ${filename}`);
    return { content: prefixedContent };
  },
  // Asynchronous processing example (recommended for heavy tasks)
  async processAsync(content, filename, options) {
    return new Promise((resolve) => {
      setTimeout(() => {
        const prefixedContent = options.prefix ? `${options.prefix} (async): ${content}` : content;
        console.log(`Processing async file: ${filename}`);
        resolve({ content: prefixedContent });
      }, 50);
    });
  }
});

// In a real application, you would register this middleware with atma-io
// For demonstration, we'll just show its structure.
console.log(`Middleware created: ${myMiddleware.name}`);

// Example of how atma-io might use it (conceptual)
const mockFileContent = 'Hello, Atma.js!';
const mockFilename = 'test.txt';
const mockOptions = { prefix: 'DEBUG' };

// Simulate synchronous process call
const syncResult = myMiddleware.process?.(mockFileContent, mockFilename, mockOptions);
console.log('Sync Result:', syncResult?.content);

// Simulate asynchronous processAsync call
myMiddleware.processAsync?.(mockFileContent, mockFilename, mockOptions)
  .then(asyncResult => console.log('Async Result:', asyncResult.content));