Registry / communication / imap-criteria-transpiler

imap-criteria-transpiler

library1.0.4jsnpmunverified

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.

communication

npm install imap-criteria-transpiler

github ↗package ↗

INSTALL

IMPORT

SIG · IMAP-CRITERIA-TRAN

imap-criteria-transpiler

communicationjavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import transpiler from 'imap-criteria-transpiler'

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

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

parse

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

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

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

type definitions

✓ import transpiler from 'imap-criteria-transpiler'; // types are exported as side-effect

✗ // no separate type import available

TypeScript types are included automatically when importing the default export. There is no explicit type export.

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(); }); });

Debug

Known issues

gotchaUnsupported 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).

affects: >=1.0.0

gotchaThe 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').

affects: >=1.0.0

gotchaThe '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)'.

affects: >=1.0.0

gotchaQuoted 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.

affects: >=1.0.0

deprecatedNo deprecations noted; package is in initial stable release.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Unexpected token at <unnamed>

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.

TypeError: transpiler.parse is not a function

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: Unknown field key: SENT

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.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/polnio/imap-criteria-transpiler ↗

packagehttps://www.npmjs.com/package/imap-criteria-transpiler ↗