### Install LibreOffice File Converter (yarn)

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/document-thumbnail.html

Install the necessary package using yarn.

```sh
yarn add libreoffice-file-converter
```

--------------------------------

### Install Fluent-FFmpeg for Video Thumbnails (yarn)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the fluent-ffmpeg module using yarn for generating video thumbnails. Ensure ffmpeg is installed on your system.

```sh
yarn add fluent-ffmpeg
```

--------------------------------

### Usage Examples: URL Management

Source: https://adonis-attachment.jrmc.dev/v4/guide/basic_usage/attachment-object.html

Examples demonstrating how to use the URL management methods to get file URLs and signed URLs.

```typescript
// Getting the URL
const url = await attachment.getUrl();

// Getting a variant URL
const variantUrl = await attachment.getUrl('thumbnail');

// Getting a signed URL
const signedUrl = await attachment.getSignedUrl({
  expiresIn: '30m'
});

// Getting a signed URL for a variant
const signedVariantUrl = await attachment.getSignedUrl('thumbnail', {
  expiresIn: '30m'
});
```

--------------------------------

### Install LibreOffice File Converter (npm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/document-thumbnail.html

Install the necessary package using npm.

```sh
npm install libreoffice-file-converter
```

--------------------------------

### Install LibreOffice File Converter (pnpm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/document-thumbnail.html

Install the necessary package using pnpm.

```sh
pnpm install libreoffice-file-converter
```

--------------------------------

### Install Fluent-FFmpeg for Video Thumbnails (npm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the fluent-ffmpeg module using npm for generating video thumbnails. Ensure ffmpeg is installed on your system.

```sh
npm install fluent-ffmpeg
```

--------------------------------

### Install FFmpeg on Ubuntu

Source: https://adonis-attachment.jrmc.dev/guide/converters/video-thumbnail.html

Install FFmpeg on Ubuntu using apt-get. This is a prerequisite for video thumbnail generation.

```sh
sudo apt-get install ffmpeg
```

--------------------------------

### Install Fluent-FFmpeg for Video Thumbnails (pnpm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the fluent-ffmpeg module using pnpm for generating video thumbnails. Ensure ffmpeg is installed on your system.

```sh
pnpm install fluent-ffmpeg
```

--------------------------------

### Install fluent-ffmpeg

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/video-thumbnail.html

Install the fluent-ffmpeg library using npm, pnpm, or yarn. This is a prerequisite for the video thumbnail converter.

```sh
npm install fluent-ffmpeg
```

```sh
pnpm install fluent-ffmpeg
```

```sh
yarn add fluent-ffmpeg
```

--------------------------------

### Install Node-Poppler for PDF Thumbnails (npm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the node-poppler module using npm for generating PDF thumbnails. Ensure poppler is installed on your system.

```sh
npm install node-poppler
```

--------------------------------

### Install Node-Poppler for PDF Thumbnails (yarn)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the node-poppler module using yarn for generating PDF thumbnails. Ensure poppler is installed on your system.

```sh
yarn add node-poppler
```

--------------------------------

### Install Sharp for Image Variants with npm

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Install the sharp module using npm to enable image variant generation.

```sh
npm install sharp
```

--------------------------------

### Usage Examples: File Management

Source: https://adonis-attachment.jrmc.dev/v4/guide/basic_usage/attachment-object.html

Examples demonstrating how to use the file management methods to access file content.

```typescript
// Getting the storage disk
const disk = attachment.getDisk();

// Getting file content as bytes
const bytes = await attachment.getBytes();

// Getting file content as buffer
const buffer = await attachment.getBuffer();

// Getting file content as stream
const stream = await attachment.getStream();
stream.pipe(fs.createWriteStream('output.jpg'));
```

--------------------------------

### Install Poppler for PDF Thumbnails on Linux

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Install poppler-utils and poppler-data on Linux systems for PDF thumbnail generation.

```sh
sudo apt-get install poppler-data poppler-utils
```

--------------------------------

### Install Node-Poppler for PDF Thumbnails (pnpm)

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/installation.html

Install the node-poppler module using pnpm for generating PDF thumbnails. Ensure poppler is installed on your system.

```sh
pnpm install node-poppler
```

--------------------------------

### Basic Route Setup

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/route-setup.html

Sets up the default route for accessing attachments. If a requested variant does not exist, it will be generated on the fly.

```typescript
// start/routes.ts
import router from '@adonisjs/core/services/router'

router.attachments()
```

--------------------------------

### Install Sharp Module

Source: https://adonis-attachment.jrmc.dev/guide/converters/image.html

Install the sharp module using npm, pnpm, or yarn. This module is required for image processing.

```bash
npm install sharp
```

```bash
pnpm install sharp
```

```bash
yarn add sharp
```

--------------------------------

### Install FFmpeg on macOS

Source: https://adonis-attachment.jrmc.dev/guide/converters/video-thumbnail.html

Install FFmpeg on macOS using Homebrew. This is a prerequisite for video thumbnail generation.

```sh
brew install ffmpeg
```

--------------------------------

### Install node-poppler

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/pdf-thumbnail.html

Install the node-poppler package using npm, pnpm, or yarn. This is a prerequisite for the PDF thumbnail converter.

```sh
npm install node-poppler
```

```sh
pnpm install node-poppler
```

```sh
yarn add node-poppler
```

--------------------------------

### Install Sharp for Image Variants with pnpm

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Install the sharp module using pnpm to enable image variant generation.

```sh
pnpm install sharp
```

--------------------------------

### Install Sharp for Image Variants with yarn

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Install the sharp module using yarn to enable image variant generation.

```sh
yarn add sharp
```

--------------------------------

### Install Poppler for PDF Thumbnails on macOS

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Install poppler on macOS using Homebrew for PDF thumbnail generation.

```sh
brew install poppler
```

--------------------------------

### Install Adonis Attachment Automatically

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Use this command to automatically install and configure the Adonis Attachment package.

```sh
node ace add @jrmc/adonis-attachment
```

--------------------------------

### Install Adonis Attachment Manually with pnpm

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Manually install the package using pnpm and then run the configure command.

```sh
pnpm install @jrmc/adonis-attachment
node ace configure @jrmc/adonis-attachment
```

--------------------------------

### Install Adonis Attachment Manually with npm

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Manually install the package using npm and then run the configure command.

```sh
npm install @jrmc/adonis-attachment
node ace configure @jrmc/adonis-attachment
```

--------------------------------

### Install Adonis Attachment Manually with yarn

Source: https://adonis-attachment.jrmc.dev/guide/essentials/installation.html

Manually install the package using yarn and then run the configure command.

```sh
yarn add @jrmc/adonis-attachment
node ace configure @jrmc/adonis-attachment
```

--------------------------------

### Install Ace Command (v2.4.0)

Source: https://adonis-attachment.jrmc.dev/changelog.html

Command to install the Adonis Attachment package using the Ace CLI.

```shell
node ace configure @jrmc/adonis-attachment
```

--------------------------------

### Basic Model Setup with @attachment

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/model-setup.html

Import the attachment decorator and Attachment type. Do not use @column with @attachment.

```typescript
import { BaseModel } from '@adonisjs/lucid/orm'
import { attachment } from '@jrmc/adonis-attachment'
import type { Attachment } from '@jrmc/adonis-attachment/types/attachment'

class User extends BaseModel {
  @attachment()
  declare avatar: Attachment
}
```

--------------------------------

### Install @adonisjs/drive (v2.0.1)

Source: https://adonis-attachment.jrmc.dev/changelog.html

Command to install the required @adonisjs/drive package for Adonis Attachment version 2.0.1 and later.

```shell
node ace add @adonisjs/drive
```

--------------------------------

### Previous Thumbnail Configuration (v4)

Source: https://adonis-attachment.jrmc.dev/migration.html

This is an example of the thumbnail configuration in v4, where the 'options' attribute was not yet optional and was required for specifying converter options.

```typescript
thumbnail: {
  converter: () => import('@jrmc/adonis-attachment/converters/autodetect_converter'),
  resize: 300,
  format: 'webp',
}
```

--------------------------------

### Configure Thumbnail Converter with Resize Object

Source: https://adonis-attachment.jrmc.dev/guide/converters/image.html

Configure a 'thumbnail' image converter using a resize object to specify width, height, fit, and position. This example uses sharp's cover fit and top position.

```typescript
import { defineConfig } from '@jrmc/adonis-attachment'
import { InferConverters } from '@jrmc/adonis-attachment/types/config'
import sharp from 'sharp'

const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      format: 'jpeg',
      resize: { // https://sharp.pixelplumbing.com/api-resize
        width: 400,
        height: 400,
        fit: sharp.fit.cover,
        position: 'top'
      },
    }
  }
})

export default attachmentConfig

declare module '@jrmc/adonis-attachment' {
  interface AttachmentVariants extends InferConverters<typeof attachmentConfig> {}
}
```

--------------------------------

### Rendering Picture Component in Edge

Source: https://adonis-attachment.jrmc.dev/guide/use-cases/picture-v2.html

Example of how to render the Picture component within an Edge template, passing the article image and alt text as props.

```edge
@!picture({
  source: article.image,
  alt: "Image alt"
})
```

--------------------------------

### Handle E_CANNOT_WRITE_FILE Exception with Session Flash and Redirect

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/exceptions.html

This example demonstrates catching the E_CANNOT_WRITE_FILE exception and using session flash messages to inform the user before redirecting them back. This is useful for user-facing error notifications.

```typescript
import { errors } from '@jrmc/adonis-attachment'

export default class HttpExceptionHandler extends ExceptionHandler {
  async handle(error: unknown, ctx: HttpContext) {
    if (error instanceof errors.E_CANNOT_WRITE_FILE) {
      ctx.session.flash('notification', {
        type: 'error',
        message: err.message,
      })

      return ctx.response.redirect('back')
    }

    return super.handle(error, ctx)
  }
}
```

--------------------------------

### Compute URL for a Single User

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/pre-compile-on-demand.html

This example shows how to compute attachment URLs for an individual user record fetched by its ID.

```typescript
const user = await User.findOrFail(1)
await User.preComputeUrls(user)

return user
```

--------------------------------

### Rendering Picture Component in Vue

Source: https://adonis-attachment.jrmc.dev/guide/use-cases/picture-v2.html

Usage example for the Vue Picture component, binding the image source and passing the alt text as props.

```vue
<Picture 
  :source="article.image" 
  alt="Image alt" 
/>
```

--------------------------------

### Configure Autodetect Converter

Source: https://adonis-attachment.jrmc.dev/guide/converters/autodetect.html

Example of how to configure the autodetect converter in the `config/attachment.ts` file. The autodetect converter is the default and can be explicitly set or left to its default behavior.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    large: {
      // => optional
      // converter: () => import('@jrmc/adonis-attachment/converters/autodetect_converter'),
      resize: 1280,
    }
  }
})
```

--------------------------------

### Configure PDF Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/guide/converters/pdf-thumbnail.html

Configure the PDF thumbnail converter to use the default settings. This snippet shows the basic setup in the attachment configuration file.

```typescript
// config/attachment.ts //
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/pdf_thumbnail_converter'),
    }
  }
})
```

--------------------------------

### Convert Animated GIF to WebP

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/custom-converter.html

This converter uses the Sharp library to transform an animated GIF into a WebP format, preserving metadata like loop and delay. Ensure Sharp is installed.

```typescript
import type { ConverterAttributes } from '@jrmc/adonis-attachment/types/converter'
import type { Input } from '@jrmc/adonis-attachment/types/input'

import Converter from '@jrmc/adonis-attachment/converters/converter'
import sharp from 'sharp'

export default class Gif2WebpConverter extends Converter {
  async handle({ input }: ConverterAttributes): Promise<Input> {
    const sharpImage = sharp(input, { animated: true, pages: -1 })

    const imageMeta = await sharpImage.metadata()
    const { loop, delay } = imageMeta

    const options = {
      webp: {
        loop,
        delay,
      }
    }

    const buffer = await sharpImage
      .withMetadata()
      .webp(options.webp)
      .toBuffer()

    return buffer
  }
}
```

--------------------------------

### Listen to Variant Started Event

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/events.html

Register a listener for the 'attachment:variant_started' event to track the beginning of variant generation. This snippet shows how to log basic information about the process.

```typescript
// start/attachment.ts
import emitter from '@adonisjs/core/services/emitter'
import type { AttachmentEventPayload } from '@jrmc/adonis-attachment/types/event'

emitter.on('attachment:variant_started', (payload: AttachmentEventPayload) => {
  console.log(`Started generating variants for ${payload.tableName}.${payload.attributeName}`)
  console.log(`Record ID: ${payload.primary.value}`)
  console.log(`Variants: ${payload.variants?.join(', ')}`)
})
```

--------------------------------

### URL Management Methods

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Methods for managing file URLs, including getting regular and signed URLs for files and their variants.

```APIDOC
## URL Management Methods

### Description
Methods for managing file URLs, including getting regular and signed URLs for files and their variants.

### Methods
#### `getUrl(variantName?: string): Promise<string>`
Gets the file URL or a variant URL.

#### `getSignedUrl(variantNameOrOptions?: string | SignedURLOptions, signedUrlOptions?: SignedURLOptions): Promise<string>`
Gets a signed URL.

### Usage Examples
```typescript
// Getting the URL
const url = await attachment.getUrl();

// Getting a variant URL
const variantUrl = await attachment.getUrl('thumbnail');

// Getting a signed URL
const signedUrl = await attachment.getSignedUrl({
  expiresIn: '30m'
});

// Getting a signed URL for a variant
const signedVariantUrl = await attachment.getSignedUrl('thumbnail', {
  expiresIn: '30m'
});
```
```

--------------------------------

### Get Attachment Content as Buffer

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Retrieve the attachment's content as a Node.js Buffer. Buffers are efficient for handling binary data.

```typescript
const buffer = await attachment.getBuffer();
```

--------------------------------

### Vue Component with Picture Variants

Source: https://adonis-attachment.jrmc.dev/guide/use-cases/picture-v2.html

A Vue.js component using the `<template>` and `<script setup>` syntax to implement responsive images with the `<picture>` element and image variants.

```vue
<template>
  <picture>
    <source media="(min-width: 1200px)" srcset="`/attachments/${article.image.keyId}/image-name.jpg?variant=large`">
    <source media="(min-width: 768px)" srcset="`/attachments/${article.image.keyId}/image-name.jpg?variant=medium`">
    <source media="(min-width: 480px)" srcset="`/attachments/${article.image.keyId}/image-name.jpg?variant=small`">
    <img src="`/attachments/${article.image.keyId}/image-name.jpg`" :alt="alt">
  </picture>
<template>

<script setup>
  defineProps({
    source: Object,
    alt: String
  })
</script>
```

--------------------------------

### Set Binary Paths Using app.makePath

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

Configure ffmpeg and ffprobe binary paths using `app.makePath` when binaries are located in the project's bin directory.

```sh
cd bin
chmod +x ffmpeg
chmod +x ffprobe
```

```typescript
import app from '@adonisjs/core/services/app'
import { defineConfig } from '@jrmc/adonis-attachment'
import { InferConverters } from '@jrmc/adonis-attachment/types/config'

const attachmentConfig = defineConfig({
  bin: {
    ffmpegPath: app.makePath('bin/ffmpeg'),
    ffprobePath: app.makePath('bin/ffprobe'),
  },
  converters: [
    // ...
  ]
})

export default attachmentConfig

declare module '@jrmc/adonis-attachment' {
  interface AttachmentVariants extends InferConverters<typeof attachmentConfig> {}
}
```

--------------------------------

### Manually Set Binary Paths

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

Specify the full paths for ffmpeg, ffprobe, pdftoppm, pdfinfo, and soffice binaries if they are not in the default system path.

```typescript
const attachmentConfig = defineConfig({
  bin: {
    ffmpegPath: 'ffmpeg_path', // the full path of the binary
    ffprobePath: 'ffprobe_path', // the full path of the binary
    pdftoppmPath: 'pdftoppm_path' // the full path of the binary
    pdfinfoPath: 'pdfinfo_path' // the full path of the binary
    sofficePath: 'soffice_path', // the full path of the binary (libreoffice/openoffice)
  },
  converters: {
    // ...
  }
})
```

--------------------------------

### Manually Set Binary Paths

Source: https://adonis-attachment.jrmc.dev/v4/guide/essentials/configuration.html

Specify manual paths for FFmpeg, FFprobe, pdftocairo, and LibreOffice binaries.

```typescript
const attachmentConfig = defineConfig({
  bin: { 
    ffmpegPath: 'ffmpeg_path', // the full path of the binary
    ffprobePath: 'ffprobe_path', // the full path of the binary
    pdftocairoBasePath: 'base_dir_path' // the path of the directory containing the binary
    libreofficePaths: [
      'libreoffice_path', // the full path of the binary
    ] // Array of paths to LibreOffice binary executables.
  },
  converters: {
    // ...
  }
})
```

--------------------------------

### Get Attachment URL

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Retrieve the direct URL for an attachment. Optionally, specify a variant name to get the URL for a specific file transformation.

```typescript
const url = await attachment.getUrl();

const variantUrl = await attachment.getUrl('thumbnail');
```

--------------------------------

### Get Storage Disk

Source: https://adonis-attachment.jrmc.dev/v4/guide/basic_usage/attachment-object.html

Access the underlying storage disk service used by the attachment for file operations.

```typescript
// Getting the storage disk
const disk = attachment.getDisk();
```

--------------------------------

### Configure Video Thumbnail Converter with Options

Source: https://adonis-attachment.jrmc.dev/guide/converters/video-thumbnail.html

Configure the video thumbnail converter with custom options for image format and resize. The 'options' attribute uses the image_converter settings.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/video_thumbnail_converter'),
      options: {
        format: 'jpeg',
        resize: 720
      }
    }
  }
})
```

--------------------------------

### Customizing Attachment Serialization

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/model-setup.html

Customize the serialized output of an attachment using a function (v4.0.0+). This example shows pre-computing URLs.

```typescript
@attachments({
  preComputeUrl: true,
  serialize: (value?: Attachment) => value?.url ?? null
})
declare avatar: Attachment | null

/**
 {
  avatar: '/uploads/lj9kbwvb8gqq8pjsmuog369l.jpg',
 }
*/
```

--------------------------------

### Create Queue Preload File

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/queue.html

Generates the necessary preload file for queue event handling.

```bash
node ace make:preload queue
```

--------------------------------

### Custom File Renaming Function

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

Use a function for the `rename` option to customize file renaming logic, for example, generating a UUID.

```typescript
import type { LucidRow } from '@adonisjs/lucid/types/model'

const attachmentConfig = defineConfig({
  rename: (file: LucidRow, column?: string, currentName?: string) => { 
    return crypto.randomUUID() 
  }, 
  converters: {
    // ...
  }
})
```

--------------------------------

### Configure Video Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/video-thumbnail.html

Configure the attachment.ts file to use the video thumbnail converter. This sets up the preview converter to import the necessary module.

```typescript
// config/attachment.ts
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/video_thumbnail_converter'),
    }
  }
})
```

--------------------------------

### Generate Custom Converter

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/custom-converter.html

Use this command to scaffold a new custom converter file. The command follows a pattern for naming and class generation.

```shell
node ace make:converter gif2webp
```

--------------------------------

### Configure Thumbnail Converter with JPEG Format

Source: https://adonis-attachment.jrmc.dev/guide/converters/image.html

Configure a 'thumbnail' image converter to resize images to 300px and output in JPEG format.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      resize: 300,
      format: 'jpeg',
    }
  }
})
```

--------------------------------

### Get Storage Disk

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Retrieve the storage disk instance associated with the attachment. This allows for further interaction with the underlying file system or cloud storage.

```typescript
const disk = attachment.getDisk();
```

--------------------------------

### Configure PDF Thumbnail Converter with Options

Source: https://adonis-attachment.jrmc.dev/guide/converters/pdf-thumbnail.html

Configure the PDF thumbnail converter with custom format and resize options. The 'options' attribute uses the image_converter settings.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/pdf_thumbnail_converter'),
      format: 'webp',
      resize: 720
    }
  }
})
```

--------------------------------

### Get Attachment Content as Bytes

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Fetch the raw byte array representation of the attachment's content. This is useful for processing file data directly in memory.

```typescript
const bytes = await attachment.getBytes();
```

--------------------------------

### Get Signed Attachment URL

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Generate a time-limited signed URL for an attachment. This is useful for granting temporary access to files. Options can specify the expiration time.

```typescript
const signedUrl = await attachment.getSignedUrl({
  expiresIn: '30m'
});

const signedVariantUrl = await attachment.getSignedUrl('thumbnail', {
  expiresIn: '30m'
});
```

--------------------------------

### Enable BlurHash Generation for Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/guide/converters/image.html

Configure a 'thumbnail' image converter to enable blurhash generation. Custom componentX and componentY values can also be specified.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      blurhash: true
      // or
      // blurhash: {
      //   enabled: true,
      //   componentX: 4,
      //   componentY: 4
      // }
    }
  }
})
```

--------------------------------

### Generating Thumbnail Variant in Edge

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/route-setup.html

Demonstrates how to generate a 'thumbnail' variant of an image using the 'assets' route alias and passing query string options in an Edge template.

```typescript
class UsersController {
  public show({ request, view }: HttpContext) {
    const user = User.first()

    return view.render('user/show', {
      user: await user.serialize()
    })
  }
}
```

```edge
// edge example
<img 
  src="{{ 
    route('assets', { key: user.avatar.getKeyId(), name: 'image-name.jpg' }, { qs: { 
      variant: 'thumbnail'
    }})
  }}"
  loading="lazy"
  alt=""
/>
```

--------------------------------

### Create Attachment Preload File

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/events.html

Use the Adonis CLI to generate a preload file for handling attachment events. This file will be executed on application startup.

```sh
node ace make:preload attachment
```

--------------------------------

### New Config Structure (v3.0.0)

Source: https://adonis-attachment.jrmc.dev/changelog.html

Configuration using defineConfig with a single object for converters. This is the newer, recommended structure.

```typescript
import { defineConfig } from '@jrmc/adonis-attachment'
import { InferConverters } from '@jrmc/adonis-attachment/types/config'

const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        resize: 300,
      }
    }
  }
})

export default attachmentConfig

declare module '@jrmc/adonis-attachment' {
  interface AttachmentVariants extends InferConverters<typeof attachmentConfig> {}
}
```

--------------------------------

### Configure Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/guide/start-here.html

Configure the 'thumbnail' converter in the attachment config file to specify the output format (webp) and resize dimensions (300px).

```ts
// config/attachment.ts
import { defineConfig } from '@jrmc/adonis-attachment'
import { InferConverters } from '@jrmc/adonis-attachment/types/config'

const attachmentConfig = defineConfig({
  converters: {
    thumbnail: { 
      format: 'webp', 
      resize: 300, 
    } 
  }
})
...
```

--------------------------------

### Monitor Failed Variant Generations

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/events.html

Implement error monitoring by listening to the 'attachment:variant_failed' event. This example logs detailed error information using the AdonisJS logger for easier debugging and tracking.

```typescript
import emitter from '@adonisjs/core/services/emitter'
import logger from '@adonisjs/core/services/logger'
import type { AttachmentEventPayload } from '@jrmc/adonis-attachment/types/event'

emitter.on('attachment:variant_failed', (payload: AttachmentEventPayload) => {
  logger.error({
    table: payload.tableName,
    attribute: payload.attributeName,
    recordId: payload.primary.value,
    variants: payload.variants,
  }, 'Variant generation failed')
})
```

--------------------------------

### Configure Document Thumbnail Converter with Custom Format and Size

Source: https://adonis-attachment.jrmc.dev/guide/converters/document-thumbnail.html

Customize the document thumbnail converter by specifying the image format (e.g., 'webp') and resize dimensions (e.g., 720). The 'options' attribute uses the image converter settings.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/document_thumbnail_converter'),
      format: 'webp',
      resize: 720
    }
  }
})
```

--------------------------------

### Get Attachment Content as Stream

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Obtain a readable stream for the attachment's content. Streams are ideal for handling large files, allowing processing without loading the entire file into memory.

```typescript
const stream = await attachment.getStream();
stream.pipe(fs.createWriteStream('output.jpg'));
```

--------------------------------

### Configure Thumbnail Converter with JPEG Quality Options

Source: https://adonis-attachment.jrmc.dev/guide/converters/image.html

Configure a 'thumbnail' image converter with specific JPEG quality options set to 80.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      resize: 300,
      format: {
        format: 'jpeg',
        options: {
          quality: 80
        }
      }
    }
  }
})
```

--------------------------------

### Drive Config for Compatibility (v2.0.1)

Source: https://adonis-attachment.jrmc.dev/changelog.html

Sample configuration for @adonisjs/drive to ensure compatibility with older versions of the attachment package.

```typescript
import env from '#start/env'
import app from '@adonisjs/core/services/app'
import { defineConfig, services } from '@adonisjs/drive'

const driveConfig = defineConfig({
  default: env.get('DRIVE_DISK'),

  services: {
    fs: services.fs({
      location: app.publicPath(), 
      serveFiles: true,
      routeBasePath: '/uploads',
      visibility: 'public',
    }),
  },
})

export default driveConfig

declare module '@adonisjs/drive/types' {
  export interface DriveDisks extends InferDriveDisks<typeof driveConfig> {}
}
```

--------------------------------

### Configure Autodetect Converter with Options

Source: https://adonis-attachment.jrmc.dev/migration.html

In v5, the 'options' attribute for converters is now optional. This snippet shows the new configuration for the thumbnail converter using autodetect with specific resize and format options.

```typescript
thumbnail: {
  converter: () => import('@jrmc/adonis-attachment/converters/autodetect_converter'),
  options: {
    resize: 300,
    format: 'webp',
  },
}
```

--------------------------------

### Article Controller Index Method

Source: https://adonis-attachment.jrmc.dev/guide/use-cases/picture-v2.html

The `index` method in the Article controller fetches all articles and serializes them, preparing them for rendering in the view. This is a standard pattern for displaying collections.

```typescript
import type { HttpContext } from '@adonisjs/core/http'

export default class ArticleController { 
  async index({ view }: HttpContext) {
    const articles = await Article.all()

    return view.render('pages/articles/index', {
      articles: (await articles?.serialize())
    })
  }
}
```

--------------------------------

### Dynamic Folder using a Function

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/model-setup.html

Specify a dynamic folder path using a function that returns a string.

```typescript
class User extends BaseModel {
  @column()
  declare name: string

  @attachment({ folder: () => DateTime.now().toFormat('yyyy/MM') })
  declare avatar: Attachment

  @attachment({ folder: (user: User) => user.name })
  declare file: Attachment
}
```

--------------------------------

### Combine Base Path and Ignore Folder Options

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

Utilize both `basePath` and `ignoreFolder` to gain granular control over variant storage. This allows storing all variants in a dedicated folder while excluding the original attachment's parent directory.

```typescript
const attachmentConfig = defineConfig({
  variant: {
    basePath: 'all-variants',
    ignoreFolder: true,
  },
  converters: {
    // ...
  }
})
```

--------------------------------

### Configure Thumbnail Converter with BlurHash

Source: https://adonis-attachment.jrmc.dev/v4/guide/converters/image.html

Enable and customize BlurHash generation for the 'thumbnail' converter. BlurHash generation is disabled by default.

```typescript
const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        blurhash: true
        // or
        // blurhash: {
        //   enabled: true,
        //   componentX: 4,
        //   componentY: 4
        // }
      }
    }
  }
})
```

--------------------------------

### Update getUrl() Usage

Source: https://adonis-attachment.jrmc.dev/changelog.html

Demonstrates the change in how to call the getUrl() method for user avatars, requiring an await.

```typescript
user.avatar.getUrl() 
await user.avatar.getUrl()
```

--------------------------------

### Configure Queue Event Handlers

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/queue.html

Sets up error handling, task completion, and drained event listeners for the attachment queue. Ensure the @jrmc/adonis-attachment and @adonisjs/core/services/logger libraries are imported.

```typescript
import { attachmentManager } from '@jrmc/adonis-attachment'
import logger from '@adonisjs/core/services/logger'

attachmentManager.queue.onError = function (error, task) {
  logger.info(`${task.name} task failed with the following error`)
  logger.error(error.message)
}

attachmentManager.queue.taskCompleted = function (task) {
  logger.info(`${task.name} completed. ${attachmentManager.queue.size()} tasks left`)
}

attachmentManager.queue.drained = function () {
  logger.info('Processed last task in the queue')
}
```

--------------------------------

### Dynamic Folder using Path Parameters

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/model-setup.html

Use path parameters in the folder definition (v4.0.0+). Only string parameters are allowed and are processed (lowercase, html escape, no case, slugify).

```typescript
class User extends BaseModel {
  @column()
  declare name: string

  @attachment({ folder: 'uploads/:name/avatars' })
  declare avatar: Attachment
}
```

--------------------------------

### Display Image using Vue Component (Options API)

Source: https://adonis-attachment.jrmc.dev/guide/start-here.html

Render an image using a Vue 'Picture' component with the Options API, passing the user's avatar source and alt text.

```svelte
<script>
import Picture from './Picture.vue'; // Assuming Picture component is in the same directory

export default {
  components: {
    Picture
  },
  props: {
    user: Object
  }
}
</script>

<template>
  <Picture 
    source={ user.avatar } 
    alt="Image alt" 
  />
</template>
```

--------------------------------

### Create Attachment from Buffer

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/controller-setup.html

Use `createFromBuffer` to create an attachment from a Buffer. You need to provide the buffer data and a filename.

```typescript
import { attachmentManager } from '@jrmc/adonis-attachment'
import app from '@adonisjs/core/services/app'

class UsersController {
  public store({ request }: HttpContext) {
    const user = new User()

    const buffer = await readFile(app.makePath('me.jpg')) 

    user.avatar = await attachmentManager.createFromBuffer(buffer, 'photo.jpg') 
    await user.save()
  }
}
```

--------------------------------

### Create Attachments from Multiple Uploaded Files

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/controller-setup.html

Use `createFromFiles` to create multiple attachments from user-uploaded files. This is available from v4.0.0.

```typescript
import { attachmentManager } from '@jrmc/adonis-attachment'

class UsersController {
  public store({ request }: HttpContext) {
    const files = request.files('files')!
    const user = new User()

    user.files = await attachmentManager.createFromFiles(files)
    await user.save()
  }
}
```

--------------------------------

### Configure Document Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/guide/converters/document-thumbnail.html

Configure the document thumbnail converter by specifying its path in the attachment configuration file. This sets up the default converter for document previews.

```typescript
// config/attachment.ts //
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/document_thumbnail_converter'),
    }
  }
})
```

--------------------------------

### File Management Methods

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/attachment-object.html

Methods for retrieving file content in various formats like bytes, buffer, or stream.

```APIDOC
## File Management Methods

### Description
Methods for retrieving file content in various formats like bytes, buffer, or stream.

### Methods
#### `getDisk(): Disk`
Gets the storage disk.

#### `getBytes(): Promise<Uint8Array>`
Gets file content as bytes.

#### `getBuffer(): Promise<Buffer>`
Gets file content as buffer.

#### `getStream(): Promise<NodeJS.ReadableStream>`
Gets file content as stream.

### Usage Examples
```typescript
// Getting the storage disk
const disk = attachment.getDisk();

// Getting file content as bytes
const bytes = await attachment.getBytes();

// Getting file content as buffer
const buffer = await attachment.getBuffer();

// Getting file content as stream
const stream = await attachment.getStream();
stream.pipe(fs.createWriteStream('output.jpg'));
```
```

--------------------------------

### Rendering Picture Component in React

Source: https://adonis-attachment.jrmc.dev/guide/use-cases/picture-v2.html

How to use the React Picture component in your application, passing the image source and alt text as props.

```jsx
<Picture 
  source={ article.image } 
  alt="Image alt" 
/>
```

--------------------------------

### Old Config Structure (v3.0.0)

Source: https://adonis-attachment.jrmc.dev/changelog.html

Configuration using defineConfig with an array of converter objects. This structure was used prior to v3.0.0.

```typescript
import { defineConfig } from '@jrmc/adonis-attachment'

export default defineConfig({
  converters: [
    {
      key: 'thumbnail',
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        resize: 300,
      }
    }
  ]
})
```

--------------------------------

### Display Image using Vue Component (Composition API)

Source: https://adonis-attachment.jrmc.dev/guide/start-here.html

Render an image using a Vue 'Picture' component with the Composition API, binding the user's avatar source and alt text.

```svelte
<script setup>
import Picture from './Picture.vue'; // Assuming Picture component is in the same directory
</script>

<template>
  <Picture 
    :source="user.avatar" 
    alt="Image alt" 
  />
</template>
```

--------------------------------

### Create Migration to Change Column Type

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/migration-setup.html

Use this command to generate a new migration file when you need to alter an existing column to a JSON data type.

```bash
# Create a new migration file
node ace make:migration change_avatar_column_to_json --table=users
```

--------------------------------

### Display Image using React Component

Source: https://adonis-attachment.jrmc.dev/guide/start-here.html

Render an image using the React 'Picture' component, passing the user's avatar source and alt text as props.

```js
<Picture 
  source={ user.avatar } 
  alt="Image alt" 
/>
```

--------------------------------

### Default Configuration

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

This is the default configuration for the Adonis Attachment package, defining thumbnail conversion settings.

```typescript
import { defineConfig } from '@jrmc/adonis-attachment'
import { InferConverters } from '@jrmc/adonis-attachment/types/config'

const attachmentConfig = defineConfig({
  converters: {
    thumbnail: {
      resize: 300,
    }
  }
})

export default attachmentConfig

declare module '@jrmc/adonis-attachment' {
  interface AttachmentVariants extends InferConverters<typeof attachmentConfig> {}
}
```

--------------------------------

### Serializing Attachments for Database Comparison

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/testing.html

Demonstrates the usage of `toDbString()` for both single attachments and arrays of attachments to match their database string representation.

```typescript
// Single attachment
avatar: user.avatar.toDbString()

// Multiple attachments
documents: JSON.stringify(user.documents.map((d) => JSON.parse(d.toDbString())))
```

--------------------------------

### Create Attachment from Uploaded File

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/controller-setup.html

Use `createFromFile` to create an attachment from a user-uploaded file. Ensure the file is correctly retrieved from the request.

```typescript
import { attachmentManager } from '@jrmc/adonis-attachment'

class UsersController {
  public store({ request }: HttpContext) {
    const avatar = request.file('avatar')!
    const user = new User()

    user.avatar = await attachmentManager.createFromFile(avatar)
    await user.save()
  }
}
```

--------------------------------

### Convert Video to Animated GIF

Source: https://adonis-attachment.jrmc.dev/guide/advanced_usage/custom-converter.html

This converter uses FFmpeg via the fluent-ffmpeg library to convert video files into animated GIFs. It handles buffer inputs by creating temporary files and allows configuration of FFmpeg binary paths.

```typescript
import type { ConverterAttributes } from '@jrmc/adonis-attachment/types/converter'
import type { Input } from '@jrmc/adonis-attachment/types/input'

import os from 'node:os'
import path from 'node:path'
import fs from 'fs/promises'
import crypto from 'node:crypto'
import Converter from '@jrmc/adonis-attachment/converters/converter'
import ffmpeg from 'fluent-ffmpeg'

export default class Video2GifConverter extends Converter {
  async handle({ input }: ConverterAttributes): Promise<Input> {
    return await this.videoToGif(ffmpeg, input)
  }

  async videoToGif(ffmpeg: Function, input: Input) {
    let file = input

    if (Buffer.isBuffer(input)) {
      file = await this.bufferToTempFile(input)
    }

    return new Promise<string>((resolve, reject) => {
      const folder = os.tmpdir()
      const filename = `${crypto.randomUUID()}.png`
      const destination = path.join(folder, filename)


      const ff = ffmpeg(file)

      if (this.binPaths) {
        if (this.binPaths.ffmpegPath) {
          ff.setFfmpegPath(this.binPaths.ffmpegPath)
        }
      }

      ff
      .withOptions([
        '-ss 1',
        `-i ${file}`,
        '-filter_complex [0:v]trim=duration=3;',
        '-f gif'
      ])
      .on('end', () => {
        resolve(destination)
      })
      .on('error', (err: Error) => {
        reject(err)
      })
      .output(destination)
      .run()
    })
  }

  async bufferToTempFile(input: Buffer) {
    const folder = os.tmpdir()
    const tempFilePath = path.join(folder, `tempfile-${Date.now()}.tmp`)
    await fs.writeFile(tempFilePath, input)
    return tempFilePath
  }
}
```

--------------------------------

### Enable Precomputed URLs

Source: https://adonis-attachment.jrmc.dev/guide/essentials/configuration.html

Set the `preComputeUrl` flag to true to precompute URLs after SELECT queries.

```typescript
const attachmentConfig = defineConfig({
  preComputeUrl: true, 
  converters: {
    // ...
  }
})
```

--------------------------------

### Specifying Disk for Attachments

Source: https://adonis-attachment.jrmc.dev/guide/basic_usage/model-setup.html

Choose a specific disk for storing attachments, defaulting to the AdonisJS Drive configuration.

```typescript
class User extends BaseModel {
  @attachment({ disk: 's3' })
  declare avatar: Attachment
}
```

--------------------------------

### Display Image using Edge Template

Source: https://adonis-attachment.jrmc.dev/guide/start-here.html

Render an image using the @!picture tag in an Edge template, passing the user's avatar source and alt text.

```edge
@!picture({
  source: user.avatar,
  alt: "Image alt"
})
```

--------------------------------

### Update Thumbnail Usage in HTML

Source: https://adonis-attachment.jrmc.dev/changelog.html

Illustrates the change in accessing the thumbnail URL for an image in an HTML template.

```html
<img :src="user.avatar.thumbnail" loading="lazy" alt="" /> // [!code --]
<img :src="user.avatar.thumbnail.url" loading="lazy" alt="" /> // [!code ++]
```

--------------------------------

### Configure Video Thumbnail Converter

Source: https://adonis-attachment.jrmc.dev/guide/converters/video-thumbnail.html

Configure the video thumbnail converter in Adonis Attachment. This involves specifying the converter path in the attachment configuration file.

```typescript
// config/attachment.ts //
const attachmentConfig = defineConfig({
  converters: {
    preview: {
      converter: () => import('@jrmc/adonis-attachment/converters/video_thumbnail_converter'),
    }
  }
})
```