comment-block-transformer 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# comment-block-transformer
+
+Transform markdown blocks based on configured transforms with middleware support.
+
+## Installation
+
+```bash
+npm install comment-block-transformer
+```
+
+## Usage
+
+The block transformer allows you to process markdown blocks with custom transforms and middleware functions.
+
+### Basic Usage
+
+```javascript
+const { blockTransformer } = require('comment-block-transformer')
+
+const text = `
+<!-- block example -->
+Some content to transform
+<!-- /block -->
+`
+
+const config = {
+  transforms: {
+    example: ({ content }) => {
+      return content.toUpperCase()
+    }
+  }
+}
+
+const result = await blockTransformer(text, config)
+console.log(result.updatedContents)
+// Output: Content will be transformed to uppercase
+```
+
+### Transform with Options
+
+You can pass options to your transforms:
+
+```javascript
+const text = `
+<!-- block prefix {"prefix": "NOTE: "} -->
+This will get a prefix
+<!-- /block -->
+`
+
+const config = {
+  transforms: {
+    prefix: ({ content, options }) => {
+      return `${options.prefix || 'PREFIX: '}${content}`
+    }
+  }
+}
+```
+
+### Multiple Transforms
+
+You can use multiple transforms in the same document:
+
+```javascript
+const text = `
+<!-- block upperCase -->
+hello world
+<!-- /block -->
+
+<!-- block reverse -->
+abc def
+<!-- /block -->
+`
+
+const config = {
+  transforms: {
+    upperCase: ({ content }) => content.toUpperCase(),
+    reverse: ({ content }) => content.split('').reverse().join('')
+  }
+}
+
+const result = await blockTransformer(text, config)
+```
+
+### Middleware Support
+
+The block transformer supports both `beforeMiddleware` and `afterMiddleware` to process content before and after transforms are applied.
+
+#### Before Middleware
+
+```javascript
+const beforeMiddleware = [
+  {
+    name: 'addPrefix',
+    transform: (blockData) => {
+      return `PREFIX: ${blockData.content.value}`
+    }
+  },
+  {
+    name: 'upperCase',
+    transform: (blockData) => {
+      return blockData.content.value.toUpperCase()
+    }
+  }
+]
+
+const config = {
+  transforms: {
+    example: (api) => api.content
+  },
+  beforeMiddleware
+}
+```
+
+#### After Middleware
+
+```javascript
+const afterMiddleware = [
+  {
+    name: 'addSuffix',
+    transform: (blockData) => {
+      return `${blockData.content.value} - PROCESSED`
+    }
+  }
+]
+
+const config = {
+  transforms: {
+    example: (api) => api.content.trim()
+  },
+  afterMiddleware
+}
+```
+
+#### Combined Middleware
+
+You can use both before and after middleware together:
+
+```javascript
+const config = {
+  transforms: {
+    example: (api) => `_${api.content.toUpperCase()}_`
+  },
+  beforeMiddleware: [
+    {
+      name: 'addBefore',
+      transform: (blockData) => `BEFORE_${blockData.content.value}`
+    }
+  ],
+  afterMiddleware: [
+    {
+      name: 'addAfter',
+      transform: (blockData) => `${blockData.content.value}_AFTER`
+    }
+  ]
+}
+```
+
+### Custom Delimiters
+
+You can customize the block delimiters:
+
+```javascript
+const text = `
+<!-- CUSTOM:START test -->
+Some content
+<!-- CUSTOM:END -->
+`
+
+const config = {
+  open: 'CUSTOM:START',
+  close: 'CUSTOM:END',
+  transforms: {
+    test: (api) => api.content.toUpperCase()
+  }
+}
+```
+
+### Custom Regex Patterns
+
+You can provide custom regex patterns for parsing:
+
+```javascript
+const config = {
+  customPatterns: {
+    open: /<!--\s*CUSTOM:START\s+(\w+)(?:\s+(\{.*?\}))?\s*-->/g,
+    close: /<!--\s*CUSTOM:END\s*-->/g
+  },
+  transforms: {
+    test: (api) => api.content.toUpperCase()
+  }
+}
+```
+
+## API Reference
+
+### blockTransformer(inputText, config)
+
+Transform markdown blocks based on configured transforms.
+
+#### Parameters
+
+- `inputText` (string): The text content to process
+- `config` (ProcessContentConfig): Configuration options
+
+#### Returns
+
+Promise<BlockTransformerResult> - Result object containing transformed content and metadata
+
+### ProcessContentConfig
+
+Configuration object for processing contents.
+
+```typescript
+interface ProcessContentConfig {
+  open?: string                    // Opening delimiter (default: 'block')
+  close?: string                   // Closing delimiter (default: '/block')
+  syntax?: string                  // Syntax type (default: 'md')
+  transforms?: TransformerPlugins  // Transform functions
+  beforeMiddleware?: Middleware[]  // Middleware functions applied before transforms
+  afterMiddleware?: Middleware[]   // Middleware functions applied after transforms
+  removeComments?: boolean         // Remove comments from output (default: false)
+  srcPath?: string                 // Source file path
+  outputPath?: string              // Output file path
+  customPatterns?: CustomPatterns  // Custom regex patterns for open and close tags
+}
+```
+
+### TransformFunction
+
+Transform function signature:
+
+```typescript
+type TransformFunction = (api: TransformApi) => Promise<string> | string
+```
+
+### TransformApi
+
+The API object passed to transform functions:
+
+```typescript
+interface TransformApi {
+  transform: string              // Name of the transform
+  content: string               // Content to transform
+  options: object               // Transform options
+  srcPath?: string              // Source file path
+  outputPath?: string           // Output file path
+  settings: object              // Additional settings including regex patterns
+  currentContent: string        // Current file contents
+  originalContent: string       // Original file contents
+  getCurrentContent(): string   // Function to get current file contents
+  getOriginalContent(): string  // Function to get original file contents
+  getOriginalBlock(): object    // Function to get the original block data
+  getBlockDetails(content?: string): object // Function to get detailed block information
+}
+```
+
+### Middleware
+
+Middleware function interface:
+
+```typescript
+interface Middleware {
+  name: string                                                    // Name of the middleware
+  transform: (blockData: BlockData, updatedText: string) => Promise<string> | string // Transform function
+}
+```
+
+### BlockTransformerResult
+
+Result object returned by blockTransformer:
+
+```typescript
+interface BlockTransformerResult {
+  isChanged: boolean           // Whether the content was changed by transforms
+  isNewPath: boolean          // Whether srcPath differs from outputPath
+  stripComments: boolean      // Whether to strip comments from output
+  srcPath?: string            // Source file path
+  outputPath?: string         // Output file path
+  transforms: BlockData[]     // Array of transforms that were applied
+  missingTransforms: any[]    // Array of transforms that were not found
+  originalContents: string    // Original input text
+  updatedContents: string     // Transformed output text
+  patterns?: object           // Regex patterns used for parsing
+}
+```
+
+## Development
+
+### Scripts
+
+- `npm test` - Run tests using uvu
+- `npm run build` - Generate TypeScript declarations
+- `npm run types` - Generate TypeScript declarations only
+- `npm run clean` - Clean generated files
+- `npm run publish` - Publish to npm
+- `npm run release:patch` - Release patch version
+- `npm run release:minor` - Release minor version
+- `npm run release:major` - Release major version
+
+### Dependencies
+
+- `comment-block-parser` - Core parsing functionality
+- `typescript` - TypeScript support (dev)
+- `uvu` - Testing framework (dev)
+
+## Testing
+
+The package uses [uvu](https://github.com/lukeed/uvu) for testing:
+
+```bash
+npm test
+```
+
+## TypeScript Support
+
+This package includes TypeScript declarations. The types are automatically generated from JSDoc comments.
+
+```bash
+npm run build
+```
+
+## License
+
+MIT

package/_usage.js

@@ -0,0 +1,60 @@
+const { blockTransformer } = require('./src')
+const deepLog = require('./test/utils/log')
+
+// Example transforms
+const transforms = {
+  // Transform that uppercases content
+  uppercase: async (api) => {
+    console.log('api', api)
+    return api.content.toUpperCase()
+  },
+  
+  // Transform that adds a prefix
+  prefix: async (api) => {
+    const { options } = api
+    return `${options.prefix || 'PREFIX: '}${api.content}`
+  }
+}
+
+// Example markdown content with transform blocks
+const content = `
+# My Document
+
+<!-- DOCS:START uppercase -->
+This will be transformed to uppercase
+<!-- DOCS:END -->
+
+<!-- DOCS:START prefix {"prefix": "NOTE: "} -->
+This will get a prefix
+<!-- DOCS:END -->
+
+Regular content that won't be transformed
+`
+
+// Process the content
+async function runExample() {
+  try {
+    const result = await blockTransformer(content, {
+      srcPath: 'example.md',
+      outputPath: 'example.output.md',
+      transforms,
+      debug: true
+    })
+
+    console.log('result.updatedContents', result.updatedContents)
+
+    // deepLog(result)
+
+    console.log('Original content:', content)
+    console.log('\nTransformed content:', result.updatedContents)
+    console.log('\nTransform details:', {
+      isChanged: result.isChanged,
+      transformsApplied: result.transforms.length,
+      missingTransforms: result.missingTransforms.length
+    })
+  } catch (error) {
+    console.error('Error:', error.message)
+  }
+}
+
+runExample()

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "comment-block-transformer",
+  "version": "0.1.0",
+  "description": "Transform markdown blocks based on configured transforms",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "dependencies": {
+    "comment-block-parser": "1.0.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "uvu": "^0.5.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "uvu test",
+    "build": "pnpm run types",
+    "types": "tsc --emitDeclarationOnly --outDir types",
+    "clean": "rimraf types",
+    "release:patch": "pnpm run build && pnpm version patch && pnpm publish",
+    "release:minor": "pnpm run build && pnpm version minor && pnpm publish",
+    "release:major": "pnpm run build && pnpm version major && pnpm publish"
+  }
+}

package/src/index.js

@@ -0,0 +1,396 @@
+const { parseBlocks } = require('comment-block-parser')
+
+const SYNTAX = 'md'
+const OPEN_WORD = 'block'
+const CLOSE_WORD = '/block'
+
+/**
+ * Types from comment-block-parser
+ * @typedef {import('comment-block-parser').BlockData} BlockData
+ * @typedef {import('comment-block-parser').ParseBlocksResult} ParseBlocksResult
+ * @typedef {import('comment-block-parser').BlockDetails} BlockDetails
+ */
+
+/**
+ * Key value pair of transform name to transform function
+ * @typedef {Record<string, TransformFunction>} TransformerPlugins
+ */
+
+/**
+ * Transform function signature
+ * @typedef {(api: TransformApi) => Promise<string>|string} TransformFunction
+ */
+
+/**
+ * Transform function API. 
+ * This is the object passed to the transform function.
+ * @typedef {Object} TransformApi
+ * @property {string} transform - Name of the transform
+ * @property {string} content - Content to transform
+ * @property {Object} options - Transform options
+ * @property {string} [srcPath] - Source file path
+ * @property {string} [outputPath] - Output file path
+ * @property {{regex: Object, [key: string]: any}} settings - Additional settings including regex patterns
+ * @property {string} currentContent - Current file contents
+ * @property {string} originalContent - Original file contents
+ * @property {() => string} getCurrentContent - Function to get current file contents
+ * @property {() => string} getOriginalContent - Function to get original file contents
+ * @property {() => BlockContext} getOriginalBlock - Function to get the original block data
+ * @property {(content?: string) => Object} getBlockDetails - Function to get detailed block information
+ */
+
+/**
+ * Extended block context with additional metadata
+ * @typedef {BlockData & {
+ *   srcPath?: string,
+ *   regex: {blocks: RegExp, open: RegExp, close: RegExp},
+ *   originalContents: string,
+ *   currentContents: string
+ * }} BlockContext
+ */
+
+/**
+ * Middleware function signature
+ * @typedef {Object} Middleware
+ * @property {string} name - Name of the middleware
+ * @property {function(BlockData, string): Promise<string>|string} transform - Transform function that takes block data and current text and returns transformed content
+ */
+
+/**
+ * Configuration object for processing contents.
+ * @typedef {Object} ProcessContentConfig
+ * @property {string} [open=OPEN_WORD] - The opening delimiter.
+ * @property {string} [close=CLOSE_WORD] - The closing delimiter.
+ * @property {string} [syntax='md'] - The syntax type.
+ * @property {TransformerPlugins} [transforms={}] - Plugins for transforms.
+ * @property {Array<Middleware>}  [beforeMiddleware=[]] - Middleware functions change inner block content before transforms.
+ * @property {Array<Middleware>}  [afterMiddleware=[]] - Middleware functions change inner block content after transforms.
+ * @property {boolean} [removeComments=false] - Remove comments from the processed contents.
+ * @property {string} [srcPath] - The source path.
+ * @property {string} [outputPath] - The output path.
+ * @property {import('comment-block-parser').CustomPatterns} [customPatterns] - Custom regex patterns for open and close tags.
+ */
+
+/**
+ * @typedef {Object} BlockTransformerResult
+ * @property {boolean} isChanged - Whether the content was changed by transforms
+ * @property {boolean} isNewPath - Whether srcPath differs from outputPath
+ * @property {boolean} stripComments - Whether to strip comments from output
+ * @property {string} [srcPath] - Source file path
+ * @property {string} [outputPath] - Output file path
+ * @property {Array<BlockData>} transforms - Array of transforms that were applied
+ * @property {Array<any>} missingTransforms - Array of transforms that were not found
+ * @property {string} originalContents - Original input text
+ * @property {string} updatedContents - Transformed output text
+ * @property {Object} [patterns] - Regex patterns used for parsing
+ */
+
+/**
+ * Transform markdown blocks based on configured transforms
+ * @param {string} inputText - The text content to process
+ * @param {ProcessContentConfig} config - Configuration options
+ * @returns {Promise<BlockTransformerResult>} Result object containing transformed content and metadata
+ */
+async function blockTransformer(inputText, config) {
+  const opts = config || {}
+
+  const {
+    srcPath,
+    outputPath,
+    open = OPEN_WORD,
+    close = CLOSE_WORD,
+    syntax = SYNTAX,
+    transforms = {},
+    beforeMiddleware = [],
+    afterMiddleware = [],
+    removeComments = false,
+    customPatterns
+  } = opts
+
+  let foundBlocks = {}
+  try {
+    foundBlocks = parseBlocks(inputText, {
+      syntax,
+      open,
+      close,
+      customPatterns
+    })
+  } catch (e) {
+    const errMsg = (srcPath) ? `in ${srcPath}` : inputText
+    throw new Error(`${e.message}\nFix content in ${errMsg}\n`)
+  }
+
+
+  const { COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX } = foundBlocks
+
+
+  const blocksWithTransforms = foundBlocks.blocks
+    .filter((block) => block.type)
+    .map((block, i) => {
+      const transform = block.type
+      delete block.type
+      return Object.assign({ transform }, block)
+    })
+
+  // console.log('blocksWithTransforms', blocksWithTransforms)
+
+  const regexInfo = {
+    blocks: foundBlocks.pattern,
+    open: COMMENT_OPEN_REGEX,
+    close: COMMENT_CLOSE_REGEX,
+  }
+
+  const transformsToRun = sortTransforms(blocksWithTransforms, transforms)
+
+  let missingTransforms = []
+  let updatedContents = await transformsToRun.reduce(async (contentPromise, originalMatch) => {
+    const updatedText = await contentPromise
+    /* Apply leading middleware */
+    const match = await applyMiddleware(originalMatch, updatedText, beforeMiddleware)
+    const { block, content, open, close, transform, options, context, index } = match
+    const closeTag = close.value
+    const openTag = open.value
+    
+    let tempContent = content.value
+    const currentTransformFn = getTransform(transform, transforms)
+
+    if (currentTransformFn) {
+      const blockContext = {
+        srcPath: config.srcPath,
+        ...match,
+        regex: regexInfo,
+        originalContents: inputText,
+        currentContents: updatedText,
+      }
+      const { transforms, srcPath, outputPath, ...restOfSettings } = opts
+
+      const returnedContent = await currentTransformFn({
+        transform, // transform name
+        content: content.value,
+        options: options || {},
+        srcPath,
+        outputPath,
+        settings: {
+          ...restOfSettings,
+          regex: blockContext.regex,
+        },
+        currentContent: updatedText,
+        originalContent: inputText,
+        getCurrentContent: () => updatedText,
+        getOriginalContent: () => inputText,
+        getOriginalBlock: () => blockContext,
+        getBlockDetails: (content) => {
+          return getDetails({
+            contents: content || updatedText,
+            openValue: open.value,
+            srcPath,
+            index,
+            opts: config
+          })
+        },
+      })
+
+      if (returnedContent) {
+        tempContent = returnedContent
+      }
+    }
+
+    /* Apply trailing middleware */
+    const afterContent = await applyMiddleware({
+      ...match,
+      ...{
+        content: {
+          ...match.content,
+          value: tempContent
+        }
+      }
+    }, updatedText, afterMiddleware)
+
+    if (!currentTransformFn) {
+      missingTransforms.push(afterContent)
+    }
+
+    let newContent = afterContent.content.value
+    /* handle different cases of typeof newContent. @TODO: make this an option */
+    if (typeof newContent === 'number') {
+      newContent = String(newContent)
+    } else if (Array.isArray(newContent)) {
+      newContent = JSON.stringify(newContent, null, 2)
+    } else if (typeof newContent === 'object') {
+      newContent = JSON.stringify(newContent, null, 2)
+    }
+
+    const formattedNewContent = (options.noTrim) ? newContent : trimString(newContent)
+    const fix = removeConflictingComments(formattedNewContent, COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX)
+
+    let preserveIndent = 0
+    if (match.content.indentation) {
+      preserveIndent = match.content.indentation.length
+    } else if (preserveIndent === 0) {
+      preserveIndent = block.indentation.length
+    }
+
+    let addTrailingNewline = ''
+    if (context.isMultiline && !fix.endsWith('\n') && fix !== '' && closeTag.indexOf('\n') === -1) {
+      addTrailingNewline = '\n'
+    }
+
+    let addLeadingNewline = ''
+    if (context.isMultiline && !fix.startsWith('\n') && fix !== '' && openTag.indexOf('\n') === -1) {
+      addLeadingNewline = '\n'
+    }
+
+    let fixWrapper = ''
+    if (!context.isMultiline && fix.indexOf('\n') > -1) {
+      fixWrapper = '\n'
+    }
+    
+    const indent = addLeadingNewline + indentString(fix, preserveIndent) + addTrailingNewline
+    const newCont = `${openTag}${fixWrapper}${indent}${fixWrapper}${closeTag}`
+    const newContents = updatedText.replace(block.value, () => newCont)
+    return Promise.resolve(newContents)
+  }, Promise.resolve(inputText))
+
+  const isNewPath = srcPath !== outputPath
+
+  if (removeComments && !isNewPath) {
+    throw new Error('"removeComments" can only be used if "outputPath" option is set. Otherwise this will break doc generation.')
+  }
+
+  const stripComments = isNewPath && removeComments
+
+  return {
+    isChanged: inputText !== updatedContents,
+    isNewPath,
+    stripComments,
+    srcPath,
+    outputPath,
+    transforms: transformsToRun,
+    missingTransforms,
+    originalContents: inputText,
+    updatedContents,
+    patterns: regexInfo,
+  }
+}
+
+/** @typedef {BlockData & { sourceLocation?: string, transform?: string }} BlockDataExtended */
+
+function getDetails({
+  contents,
+  openValue,
+  srcPath,
+  index,
+  opts
+}) {
+  const blockData = parseBlocks(contents, opts)
+  const matchingBlocks = blockData.blocks.filter((block) => {
+    return block.open.value === openValue
+  })
+
+  if (!matchingBlocks.length) {
+    return {}
+  }
+
+  /** @type {BlockDataExtended} */
+  let foundBlock = matchingBlocks[0]
+  if (matchingBlocks.length > 1 && index) {
+    foundBlock = matchingBlocks.filter((block) => {
+      return block.index === index
+    })[0]
+  }
+
+  if (srcPath) {
+    const location = getCodeLocation(srcPath, foundBlock.block.lines[0])
+    foundBlock.sourceLocation = location
+  }
+  return foundBlock
+}
+
+function removeConflictingComments(content, openPattern, closePattern) {
+  const removeOpen = content.replace(openPattern, '')
+  closePattern.lastIndex = 0
+  const hasClose = closePattern.exec(content)
+  if (!hasClose) {
+    return removeOpen
+  }
+  const closeTag = `${hasClose[2]}${hasClose[3] || ''}`
+  return removeOpen
+    .replace(closePattern, '')
+    .replace(/\n$/, '')
+}
+
+/**
+ * Apply middleware functions to block data
+ * @param {BlockData} data - The block data to transform
+ * @param {string} updatedText - The current updated text content
+ * @param {Array<Middleware>} middlewares - Array of middleware functions to apply
+ * @returns {Promise<BlockDataExtended>} The transformed block data
+ */
+function applyMiddleware(data, updatedText, middlewares) {
+  return middlewares.reduce(async (acc, curr) => {
+    const blockData = await acc
+    const updatedContent = await curr.transform(blockData, updatedText)
+    return Promise.resolve({
+      ...blockData,
+      ...{
+        content: {
+          ...blockData.content,
+          value: updatedContent
+        }
+      }
+    })
+  }, Promise.resolve(data))
+}
+
+function getTransform(name, transforms = {}) {
+  return transforms[name] || transforms[name.toLowerCase()]
+}
+
+function sortTransforms(foundTransForms, registeredTransforms) {
+  if (!foundTransForms) return []
+  return foundTransForms.sort((a, b) => {
+    if (a.transform === 'TOC' || a.transform === 'sectionToc') return 1
+    if (b.transform === 'TOC' || b.transform === 'sectionToc') return -1
+    return 0
+  }).map((item) => {
+    if (getTransform(item.transform, registeredTransforms)) {
+      return item
+    }
+    return {
+      ...item,
+      context: {
+        ...item.context,
+        isMissing: true,
+      }
+    }
+  })
+}
+
+/**
+ * Indent a string by a specified number of spaces
+ * @param {string} str - The string to indent
+ * @param {number} count - Number of spaces to indent by
+ * @returns {string} The indented string
+ */
+function indentString(str, count) {
+  if (!str) return str
+  return str.split('\n').map(line => ' '.repeat(count) + line).join('\n')
+}
+
+/**
+ * Trim whitespace from a string
+ * @param {string} str - The string to trim
+ * @returns {string} The trimmed string
+ */
+function trimString(str) {
+  if (!str) return str
+  return str.trim()
+}
+
+function getCodeLocation(srcPath, line, column = '0') {
+  return `${srcPath}:${line}:${column}`
+}
+
+module.exports = {
+  blockTransformer
+} 

package/test/index.test.js

@@ -0,0 +1,319 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { blockTransformer } = require('../src')
+
+/** @typedef {import('../src').ProcessContentConfig} ProcessContentConfig */
+
+// Mock some core transforms for testing
+const mockCoreTransforms = {
+  TOC: (api) => {
+    return '# Table of Contents\n- [Example](#example)'
+  },
+  FILE: (api) => {
+    return `File content from ${api.options.src || 'unknown file'}`
+  },
+  CODE: (api) => {
+    return `\`\`\`\n// Code from ${api.options.src || 'unknown source'}\n\`\`\``
+  }
+}
+
+test('should transform markdown blocks', async () => {
+  const text = `
+<!-- block test -->
+Some content
+<!-- /block -->
+  `
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      test: (api) => {
+        return api.content.toUpperCase()
+      }
+    }
+  }
+
+  const result = await blockTransformer(text, config)
+  // console.log('result', result)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('SOME CONTENT'))
+})
+
+test('should handle missing transforms', async () => {
+  const text = `
+<!-- block foobar -->
+This will be transformed to uppercase
+<!-- /block -->
+  `
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {}
+  }
+
+  const result = await blockTransformer(text, config)
+  console.log('result', result)
+  assert.is(result.missingTransforms.length, 1)
+})
+
+test('should apply middleware', async () => {
+  const text = `
+<!-- block foobar -->
+Some content
+<!-- /block -->
+  `
+  const beforeMiddleware = [{
+    name: 'test',
+    transform: (blockData) => {
+      console.log('blockData', blockData)
+      return blockData.content.value.toUpperCase()
+    }
+  }]
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {},
+    beforeMiddleware
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.ok(result.updatedContents.includes('SOME CONTENT'))
+})
+
+test('should handle custom delimiters', async () => {
+  const text = `
+<!-- CUSTOM:START test -->
+Some content
+<!-- CUSTOM:END -->
+  `
+  /** @type {ProcessContentConfig} */
+  const config = {
+    open: 'CUSTOM:START',
+    close: 'CUSTOM:END',
+    transforms: {
+      test: (api) => {
+        return api.content.toUpperCase()
+      }
+    }
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('SOME CONTENT'))
+})
+
+test('should handle multiple plugins', async () => {
+  const text = `
+<!-- block upperCase -->
+hello world
+<!-- /block -->
+
+<!-- block reverse -->
+abc def
+<!-- /block -->
+
+<!-- block addPrefix -->
+content here
+<!-- /block -->
+  `
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      upperCase: (api) => {
+        return api.content.toUpperCase()
+      },
+      reverse: (api) => {
+        return api.content.split('').reverse().join('')
+      },
+      addPrefix: (api) => {
+        return `PREFIX: ${api.content}`
+      }
+    }
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('HELLO WORLD'))
+  assert.ok(result.updatedContents.includes('fed cba'))
+  assert.ok(result.updatedContents.includes('PREFIX: content here'))
+  assert.is(result.transforms.length, 3)
+})
+
+test('should handle multiple before middlewares', async () => {
+  const text = `
+<!-- block test -->
+hello world
+<!-- /block -->
+  `
+  const beforeMiddleware = [
+    {
+      name: 'upperCase',
+      transform: (blockData) => {
+        return blockData.content.value.toUpperCase()
+      }
+    },
+    {
+      name: 'addExclamation',
+      transform: (blockData) => {
+        return blockData.content.value + '!'
+      }
+    },
+    {
+      name: 'addPrefix',
+      transform: (blockData) => {
+        return `PREFIX: ${blockData.content.value}`
+      }
+    }
+  ]
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      test: (api) => {
+        return api.content
+      }
+    },
+    beforeMiddleware
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('PREFIX: HELLO WORLD!'))
+})
+
+test('should handle multiple after middlewares', async () => {
+  const text = `
+<!-- block test -->
+hello world
+<!-- /block -->
+  `
+  const afterMiddleware = [
+    {
+      name: 'upperCase',
+      transform: (blockData) => {
+        return blockData.content.value.toUpperCase()
+      }
+    },
+    {
+      name: 'addSuffix',
+      transform: (blockData) => {
+        return `${blockData.content.value} - PROCESSED`
+      }
+    },
+    {
+      name: 'wrapBrackets',
+      transform: (blockData) => {
+        return `[${blockData.content.value}]`
+      }
+    }
+  ]
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      test: (api) => {
+        return api.content.trim()
+      }
+    },
+    afterMiddleware
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('[HELLO WORLD - PROCESSED]'))
+})
+
+test('should handle both before and after middlewares together', async () => {
+  const text = `
+<!-- block test -->
+content
+<!-- /block -->
+  `
+  const beforeMiddleware = [
+    {
+      name: 'addBefore',
+      transform: (blockData) => {
+        return `BEFORE_${blockData.content.value}`
+      }
+    }
+  ]
+  const afterMiddleware = [
+    {
+      name: 'addAfter',
+      transform: (blockData) => {
+        return `${blockData.content.value}_AFTER`
+      }
+    }
+  ]
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      test: (api) => {
+        return `_${api.content.toUpperCase()}_`
+      }
+    },
+    beforeMiddleware,
+    afterMiddleware
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('_BEFORE_CONTENT__AFTER'))
+})
+
+test('should handle multiple plugins with core transforms', async () => {
+  const text = `
+<!-- block upperCase -->
+hello world
+<!-- /block -->
+
+<!-- block TOC -->
+<!-- /block -->
+  `
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      upperCase: (api) => {
+        return api.content.toUpperCase()
+      },
+      ...mockCoreTransforms
+    }
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('HELLO WORLD'))
+  assert.ok(result.updatedContents.includes('Table of Contents'))
+  assert.is(result.transforms.length, 2)
+})
+
+test('should apply middlewares to multiple blocks independently', async () => {
+  const text = `
+<!-- block block1 -->
+first block
+<!-- /block -->
+
+<!-- block block2 -->
+second block
+<!-- /block -->
+  `
+  const beforeMiddleware = [
+    {
+      name: 'addIndex',
+      transform: (blockData) => {
+        const blockIndex = blockData.transform === 'block1' ? '1' : '2'
+        return `Block ${blockIndex}: ${blockData.content.value}`
+      }
+    }
+  ]
+  /** @type {ProcessContentConfig} */
+  const config = {
+    transforms: {
+      block1: (api) => api.content.toUpperCase(),
+      block2: (api) => api.content.toLowerCase()
+    },
+    beforeMiddleware
+  }
+
+  const result = await blockTransformer(text, config)
+  assert.is(result.isChanged, true)
+  assert.ok(result.updatedContents.includes('BLOCK 1: FIRST BLOCK'))
+  assert.ok(result.updatedContents.includes('block 2: second block'))
+})
+
+test.run() 

package/test/utils/log.js

@@ -0,0 +1,20 @@
+const util = require('util')
+
+
+function logValue(value, isFirst, isLast) {
+  const prefix = `${isFirst ? '> ' : ''}`
+  if (typeof value === 'object') {
+    console.log(`${util.inspect(value, false, null, true)}\n`)
+    return
+  }
+  if (isFirst) {
+    console.log(`\n\x1b[33m${prefix}${value}\x1b[0m`)
+    return
+  }
+  console.log((typeof value === 'string' && value.includes('\n')) ? `\`${value}\`` : value)
+  // isLast && console.log(`\x1b[37m\x1b[1m${'─'.repeat(94)}\x1b[0m\n`)
+}
+
+module.exports = function deepLog() {
+  for (let i = 0; i < arguments.length; i++) logValue(arguments[i], i === 0, i === arguments.length - 1)
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "noEmit": false,
+    "declarationDir": "./types"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}