imap-criteria-transpiler

1.0.4 verified Fri May 01 auth: no javascript

A library that converts human-readable query strings (e.g., 'from:foo AND to:bar') into IMAP search criteria arrays for use with Node.js IMAP libraries. Version 1.0.4 is the latest stable release with no major changes since initial release. It supports logical operators (AND, OR, NOT), parentheses for precedence, and quote/backslash escaping. Unlike building criteria manually, it provides a simple DSL for dynamic IMAP query generation. Ships TypeScript type declarations, making it suitable for TypeScript projects. Currently only supports a subset of IMAP search keys (e.g., FROM, TO, SUBJECT) - see documentation for full list.

Common errors

error SyntaxError: Unexpected token at <unnamed> ↓

cause Query contains unsupported characters or invalid syntax (e.g., mismatched parentheses, unexpected operators).

fix

Check for balanced parentheses and ensure colons are used correctly (e.g., 'from:value' not 'from: value'). Use quotes around values with spaces.

error TypeError: transpiler.parse is not a function ↓

cause Incorrect import: using named import ({ parse }) or destructuring from module.

fix

Use default import: import transpiler from 'imap-criteria-transpiler'. Then call transpiler.parse(query).

error Error: Unknown field key: SENT ↓

cause Query uses 'sent' which is not a supported IMAP key. Supported keys are limited.

fix

Replace 'sent' with 'SINCE' if you mean date, or check the list of supported fields in the README.

Warnings

gotcha Unsupported or misspelled field keys (e.g., 'SENT' instead of 'SINCE') produce an Error during parsing, not a silent omission. ↓

fix Refer to the list of supported IMAP keys: FROM, TO, SUBJECT, BODY, TEXT, BEFORE, ON, SINCE, FLAGGED, UNFLAGGED, SEEN, UNSEEN, ANSWERED, UNANSWERED, DELETED, UNDELETED, DRAFT, UNDRAFT, NEW, OLD, RECENT, ALL. Use exact uppercase or lowercase (case-insensitive).

gotcha The parser does NOT validate the structure of criteria for IMAP validity; it only produces the array. An empty query string returns an empty array []. Passing an empty array to IMAP search may cause errors depending on the IMAP library. ↓

fix Always check that the parsed criteria array has at least one element before using in IMAP search. Example: if (criteria.length === 0) throw new Error('Query is empty').

gotcha The 'AND' operator is the implicit default between consecutive terms. Using explicit 'AND' is optional but may lead to confusion if mixed with 'OR' and not using parentheses correctly. ↓

fix Always wrap OR conditions in parentheses to ensure correct precedence: 'from:alice OR from:bob AND subject:hi' is interpreted as 'from:alice OR (from:bob AND subject:hi)'. Use parentheses explicitly to group OR: 'from:alice OR (from:bob AND subject:hi)'.

gotcha Quoted strings inside field values (e.g., subject:"hello world") are supported but double quotes must be used; single quotes are not supported for escaping values. ↓

fix Use double quotes around field values that contain spaces. Example: 'subject:"urgent reminder"'. Single quotes are treated as part of the string.

deprecated No deprecations noted; package is in initial stable release.

Install

npm install imap-criteria-transpiler

yarn add imap-criteria-transpiler

pnpm add imap-criteria-transpiler

Imports

default

wrong

import { transpiler } from 'imap-criteria-transpiler'

correct

import transpiler from 'imap-criteria-transpiler'

The package exports a default object with a `parse` method. Named import is incorrect.

parse

wrong

import { parse } from 'imap-criteria-transpiler'

correct

import transpiler from 'imap-criteria-transpiler'; const criteria = transpiler.parse(query)

Cannot destructure parse from module because default export is not a plain object that supports destructuring of parse by name.

type definitions
wrong
```
// no separate type import available
```
correct
```
import transpiler from 'imap-criteria-transpiler'; // types are exported as side-effect
```
TypeScript types are included automatically when importing the default export. There is no explicit type export.

Quickstart

Demonstrates parsing a complex query with AND, OR, parentheses, and quotes into IMAP criteria array, then using it in a search.

import transpiler from 'imap-criteria-transpiler';

const query = 'from:alice AND (subject:"urgent" OR subject:report)';
const criteria = transpiler.parse(query);
console.log(criteria);
// Output: [['HEADERS', 'FROM', 'alice'], ['OR', ['HEADERS', 'SUBJECT', 'urgent'], ['HEADERS', 'SUBJECT', 'report']]]

// Use with a hypothetical IMAP client
const imap = require('imap');
const client = new imap({ user: 'user', password: 'pass', host: 'imap.example.com' });
client.connect(() => {
  client.search(criteria, (err, uuids) => {
    if (err) throw err;
    console.log('Found UIDs:', uuids);
    client.end();
  });
});