ampscript-data

Canonical AMPscript function catalog, keywords, and personalization strings for Salesforce Marketing Cloud (SFMC) tooling.

This package is the single source of truth consumed by:

• eslint-plugin-sfmc — unknown-function detection and arity validation
• prettier-plugin-sfmc — casing normalization
• VSCode: sfmc-language — completions, hover, and diagnostics

Installation

npm install ampscript-data

Usage

import {
    FUNCTIONS,
    AMPSCRIPT_KEYWORDS,
    AMPSCRIPT_GLOBALS,
    PERSONALIZATION_STRINGS,
    DEPRECATED_FUNCTIONS,
    functionLookup,
    functionNames,
    CANONICAL_FUNCTIONS,
    FUNCTION_CANONICAL_MAP,
    deprecatedFunctionLookup,
    isEmailExcluded,
    isMcnSupported,
    getMcnApiVersion,
    getMcnNotes,
    VERIFICATION_BLOCKED_REASONS,
} from 'ampscript-data';

FUNCTIONS

An array of all known AMPscript functions with full metadata:

import { FUNCTIONS } from 'ampscript-data';

for (const fn of FUNCTIONS) {
    console.log(fn.name);        // e.g. 'Lookup'
    console.log(fn.minArgs);     // minimum argument count
    console.log(fn.maxArgs);     // maximum argument count (Infinity = variadic)
    console.log(fn.category);    // e.g. 'Data Extension'
    console.log(fn.description); // human-readable description
    console.log(fn.params);      // array of { name, description, type?, optional? }
    console.log(fn.returnType);  // e.g. 'string'
    console.log(fn.syntax);      // canonical signature string
    console.log(fn.example);     // usage example (where available)
    console.log(fn.docUrl);      // URL to official Salesforce developer docs
    console.log(fn.guideUrl);    // URL to ampscript.guide reference page
    console.log(fn.sfmcGuideUrl); // URL to our own sfmc.guide reference page (only when published)
    console.log(fn.mcnSince);    // API version when MCN support was added (null = MCE only)
    console.log(fn.mcnNotes);    // behavioral differences on MCN (null = none)
    console.log(fn.handlebarsEquivalent); // MCN Handlebars helper name, or null when none exists
    console.log(fn.handlebarsExact);      // true = drop-in replacement, false = same job, different call shape
}

Optional: sfmcGuideUrl

docUrl and guideUrl point at third-party documentation and are set for (almost) every function. sfmcGuideUrl is different: it links to our own published reference page and only exists once that page has been written, which happens at the end of a runtime verification sweep. It is therefore a reliable marker for "this function has a proven, self-hosted reference page":

const entry = functionLookup.get('add');
entry.sfmcGuideUrl; // 'https://sfmc.guide/engagement/ampscript/functions/add/'

The URL is always https://sfmc.guide/engagement/ampscript/functions/<lowercase-name>/, and an entry carrying it is always isConfirmed: true.

Optional: validArities

Most functions accept any argument count in the contiguous minArgs..maxArgs range. A function with a discontinuous overload — where intermediate counts are invalid — additionally sets validArities, the exact set of permitted argument counts:

import { functionLookup } from 'ampscript-data';

const entry = functionLookup.get('somefunction');
if (entry.validArities) {
    // e.g. minArgs: 1, maxArgs: 6, validArities: [1, 6] — 2-5 arguments are invalid
    const isValidCall = entry.validArities.includes(argumentCount);
}

The array is always strictly ascending integers and includes both minArgs (first element) and maxArgs (last element). When absent, the arity range is purely contiguous — which is currently the case for every AMPscript function.

Optional: verification state

| Field | Type | Description | |---|---|---| | isConfirmed | boolean | true when the behavior was verified against the live AMPscript engine; absent means never checked | | verificationBlocked | boolean | true when verification was attempted but could not complete; requires isConfirmed: false and a verificationBlockedReason | | verificationBlockedReason | string | One of VERIFICATION_BLOCKED_REASONS; only valid together with verificationBlocked: true | | differsFromOfficialDocs | boolean | true when the verified runtime behavior contradicts the official Salesforce reference; requires officialDocsNote | | officialDocsNote | string | What the official docs claim, what the runtime actually did, and what was tried |

VERIFICATION_BLOCKED_REASONS

A frozen array of the blocker categories that may be used as verificationBlockedReason:

import { VERIFICATION_BLOCKED_REASONS } from 'ampscript-data';
// ['no-working-invocation', 'needs-auth-context', 'no-test-data',
//  'classic-only-no-assets', 'destructive-unsafe']

| Value | Meaning | |---|---| | no-working-invocation | Probing found no invocation shape that works | | needs-auth-context | Requires an authenticated / session / subscriber state the probe context cannot supply | | no-test-data | Requires pre-existing data or an integration not provisioned on the BU | | classic-only-no-assets | Only works with classic (legacy) assets and none exist to test against | | destructive-unsafe | Cannot be exercised without unacceptable side effects |

functionLookup

A Map<string, FunctionEntry> keyed by lowercase function name for O(1) lookups:

import { functionLookup } from 'ampscript-data';

const entry = functionLookup.get('lookup');

functionNames

A Set<string> of all function names in lowercase — useful for existence checks:

import { functionNames } from 'ampscript-data';

if (functionNames.has('lookup')) { /* ... */ }

CANONICAL_FUNCTIONS

An array of function names in their canonical casing (e.g. 'Lookup'), used for casing normalization:

import { CANONICAL_FUNCTIONS } from 'ampscript-data';

FUNCTION_CANONICAL_MAP

A Map<string, string> from lowercase name to canonical-cased name:

import { FUNCTION_CANONICAL_MAP } from 'ampscript-data';

FUNCTION_CANONICAL_MAP.get('lookup'); // 'Lookup'

DEPRECATED_FUNCTIONS

An array of deprecated function entries with the same shape as FUNCTIONS:

import { DEPRECATED_FUNCTIONS } from 'ampscript-data';

deprecatedFunctionLookup

A Map<string, FunctionEntry> for deprecated functions, keyed by lowercase name:

import { deprecatedFunctionLookup } from 'ampscript-data';

isEmailExcluded

Returns true if the function is not available in email send contexts:

import { isEmailExcluded } from 'ampscript-data';

isEmailExcluded('HTTPGet'); // true — not available in email

Marketing Cloud Next (MCN) compatibility

Each FunctionEntry has these MCN fields:

| Field | Type | Description | |---|---|---| | mcnSince | number \| null | API version when MCN support was added (e.g. 67); null means MCE only | | mcnNotes | string \| null | Behavioral differences on MCN vs MCE; null means no known differences | | handlebarsEquivalent | string \| null | Name of the MCN Handlebars helper that replaces this function (e.g. 'add'); null when no counterpart exists | | handlebarsExact | boolean | Only meaningful when handlebarsEquivalent is set: true = argument-for-argument drop-in, false = same job but different call shape (converter emits a hint) |

handlebarsEquivalent and handlebarsExact drive AMPscript ↔ Handlebars conversion tooling. When handlebarsExact is false, the helper does the same job but with a different call shape, so conversion emits a hint for a human to finish rather than a mechanical substitution.

Three helper functions are exported for programmatic MCN checks:

isMcnSupported

Returns true when the function is available on Marketing Cloud Next:

import { isMcnSupported } from 'ampscript-data';

isMcnSupported('Lookup');   // true
isMcnSupported('HTTPGet');  // false

getMcnApiVersion

Returns the API version number (e.g. 67) when MCN support was added, or null for MCE-only functions:

import { getMcnApiVersion } from 'ampscript-data';

getMcnApiVersion('Lookup');  // 67
getMcnApiVersion('HTTPGet'); // null

getMcnNotes

Returns a string describing behavioral differences on MCN, or null when the function behaves identically across platforms:

import { getMcnNotes } from 'ampscript-data';

getMcnNotes('FormatDate');    // "In Marketing Cloud Next, this function uses ..."
getMcnNotes('Lookup');        // "In Marketing Cloud Next, an odd number of search ..."
getMcnNotes('ProperCase');    // null

AMPSCRIPT_KEYWORDS

An array of AMPscript language keyword descriptors (if, for, set, etc.). Each entry carries a short description and a completion snippet with ${n:placeholder} tab stops:

import { AMPSCRIPT_KEYWORDS } from 'ampscript-data';

for (const kw of AMPSCRIPT_KEYWORDS) {
    console.log(kw.name);        // e.g. 'if'
    console.log(kw.description); // human-readable description
    console.log(kw.snippet);     // completion body, e.g. 'if ${1:condition} then\n\t${2}\nendif'
}

AMPSCRIPT_GLOBALS

An array of read-only AMPscript language globals that are not subscriber personalization attributes:

import { AMPSCRIPT_GLOBALS } from 'ampscript-data';

for (const global of AMPSCRIPT_GLOBALS) {
    console.log(global.name);        // e.g. '@@ExecCtx'
    console.log(global.description); // human-readable description
}

PERSONALIZATION_STRINGS

An array of AMPscript system personalization string descriptors, including subscriber attributes and message-context values:

import { PERSONALIZATION_STRINGS } from 'ampscript-data';

for (const ps of PERSONALIZATION_STRINGS) {
    console.log(ps.name);        // e.g. 'emailaddr'
    console.log(ps.description); // human-readable description
}

License

MIT