{"id":25753,"library":"imap-criteria-transpiler","title":"imap-criteria-transpiler","description":"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.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/polnio/imap-criteria-transpiler","tags":["javascript","typescript"],"install":[{"cmd":"npm install imap-criteria-transpiler","lang":"bash","label":"npm"},{"cmd":"yarn add imap-criteria-transpiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add imap-criteria-transpiler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports a default object with a `parse` method. Named import is incorrect.","wrong":"import { transpiler } from 'imap-criteria-transpiler'","symbol":"default","correct":"import transpiler from 'imap-criteria-transpiler'"},{"note":"Cannot destructure parse from module because default export is not a plain object that supports destructuring of parse by name.","wrong":"import { parse } from 'imap-criteria-transpiler'","symbol":"parse","correct":"import transpiler from 'imap-criteria-transpiler'; const criteria = transpiler.parse(query)"},{"note":"TypeScript types are included automatically when importing the default export. There is no explicit type export.","wrong":"// no separate type import available","symbol":"type definitions","correct":"import transpiler from 'imap-criteria-transpiler'; // types are exported as side-effect"}],"quickstart":{"code":"import transpiler from 'imap-criteria-transpiler';\n\nconst query = 'from:alice AND (subject:\"urgent\" OR subject:report)';\nconst criteria = transpiler.parse(query);\nconsole.log(criteria);\n// Output: [['HEADERS', 'FROM', 'alice'], ['OR', ['HEADERS', 'SUBJECT', 'urgent'], ['HEADERS', 'SUBJECT', 'report']]]\n\n// Use with a hypothetical IMAP client\nconst imap = require('imap');\nconst client = new imap({ user: 'user', password: 'pass', host: 'imap.example.com' });\nclient.connect(() => {\n  client.search(criteria, (err, uuids) => {\n    if (err) throw err;\n    console.log('Found UIDs:', uuids);\n    client.end();\n  });\n});","lang":"typescript","description":"Demonstrates parsing a complex query with AND, OR, parentheses, and quotes into IMAP criteria array, then using it in a search."},"warnings":[{"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).","message":"Unsupported or misspelled field keys (e.g., 'SENT' instead of 'SINCE') produce an Error during parsing, not a silent omission.","severity":"gotcha","affected_versions":">=1.0.0"},{"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').","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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)'.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use double quotes around field values that contain spaces. Example: 'subject:\"urgent reminder\"'. Single quotes are treated as part of the string.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"","message":"No deprecations noted; package is in initial stable release.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Check for balanced parentheses and ensure colons are used correctly (e.g., 'from:value' not 'from: value'). Use quotes around values with spaces.","cause":"Query contains unsupported characters or invalid syntax (e.g., mismatched parentheses, unexpected operators).","error":"SyntaxError: Unexpected token at <unnamed>"},{"fix":"Use default import: import transpiler from 'imap-criteria-transpiler'. Then call transpiler.parse(query).","cause":"Incorrect import: using named import ({ parse }) or destructuring from module.","error":"TypeError: transpiler.parse is not a function"},{"fix":"Replace 'sent' with 'SINCE' if you mean date, or check the list of supported fields in the README.","cause":"Query uses 'sent' which is not a supported IMAP key. Supported keys are limited.","error":"Error: Unknown field key: SENT"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}