ampscript-data 3.7.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,6 +32,7 @@ import {
32
32
  isMcnSupported,
33
33
  getMcnApiVersion,
34
34
  getMcnNotes,
35
+ BOOLEAN_LIKE_LITERAL_VALUES,
35
36
  VERIFICATION_BLOCKED_REASONS,
36
37
  } from 'ampscript-data';
37
38
  ```
@@ -90,6 +91,18 @@ if (entry.validArities) {
90
91
 
91
92
  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.
92
93
 
94
+ #### Boolean-like flag values
95
+
96
+ Boolean-like function parameters use a shared frozen enum covering the eight accepted AMPscript literal forms:
97
+
98
+ ```js
99
+ import { BOOLEAN_LIKE_LITERAL_VALUES } from 'ampscript-data';
100
+
101
+ // [true, false, 1, 0, 'true', 'false', '1', '0']
102
+ ```
103
+
104
+ These parameters use the `string|boolean|number` type and reference this array through their `enum` field.
105
+
93
106
  #### Optional: verification state
94
107
 
95
108
  | Field | Type | Description |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ampscript-data",
3
- "version": "3.7.0",
3
+ "version": "4.1.0",
4
4
  "description": "Canonical AMPscript function catalog, keywords, and personalization strings for SFMC tooling",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -29,7 +29,7 @@
29
29
  ],
30
30
  "license": "MIT",
31
31
  "scripts": {
32
- "test": "echo No tests defined",
32
+ "test": "node --test tests/*.test.mjs",
33
33
  "lint": "eslint .",
34
34
  "lint:fix": "eslint --fix .",
35
35
  "prepare": "husky || true",
@@ -0,0 +1,63 @@
1
+ // AUTO-SPLIT from the original single-file src/index.js. Data moved verbatim.
2
+ // Shared constants used across the split data files.
3
+
4
+ /**
5
+ * Sentinel for variadic functions (maxArgs === Infinity).
6
+ */
7
+ export const INF = Infinity;
8
+
9
+ /**
10
+ * Boolean-like literal values accepted by AMPscript flag parameters.
11
+ *
12
+ * @type {readonly (boolean|number|string)[]}
13
+ */
14
+ export const BOOLEAN_LIKE_LITERAL_VALUES = Object.freeze([
15
+ true,
16
+ false,
17
+ 1,
18
+ 0,
19
+ 'true',
20
+ 'false',
21
+ '1',
22
+ '0',
23
+ ]);
24
+
25
+ // ── Verification-blocked reasons ─────────────────────────────────────────────
26
+ // Fixed enum of concrete technical/environmental reasons why a runtime verification
27
+ // was ATTEMPTED but could not complete. Set on an entry as `verificationBlockedReason`
28
+ // together with `verificationBlocked: true` and `isConfirmed: false`. The specific
29
+ // evidence (error text, invocation shapes tried) belongs in `officialDocsNote`, not here.
30
+ //
31
+ // - no-working-invocation no invocation shape that works was found; document
32
+ // exactly what was tried in officialDocsNote.
33
+ // - needs-auth-context requires an authenticated / session / subscriber state that
34
+ // a plain CloudPage cannot supply
35
+ // - no-test-data requires pre-existing data or an integration that is not
36
+ // provisioned on the BU
37
+ // - classic-only-no-assets only works with classic (legacy) assets and none exist
38
+ // on the BU to test against
39
+ // - destructive-unsafe cannot be observed without unacceptable side effects
40
+ /**
41
+ @type {readonly string[]}
42
+ */
43
+ export const VERIFICATION_BLOCKED_REASONS = Object.freeze([
44
+ 'no-working-invocation',
45
+ 'needs-auth-context',
46
+ 'no-test-data',
47
+ 'classic-only-no-assets',
48
+ 'destructive-unsafe',
49
+ ]);
50
+
51
+ export const EMAIL_EXCLUDED_CATEGORIES = new Set(['Marketing Cloud API']);
52
+
53
+ export const EMAIL_EXCLUDED_FUNCTIONS = new Set([
54
+ 'insertdata',
55
+ 'updatedata',
56
+ 'upsertdata',
57
+ 'deletedata',
58
+ 'redirect',
59
+ 'requestparameter',
60
+ 'queryparameter',
61
+ 'httprequestheader',
62
+ 'isctmlbrowser',
63
+ ]);
package/src/derived.js ADDED
@@ -0,0 +1,100 @@
1
+ // AUTO-SPLIT from the original single-file src/index.js. Logic moved verbatim.
2
+ // Lookups, canonical-casing maps, deprecated/non-functional lookups and the
3
+ // email/MCN helper functions derived from the FUNCTIONS catalog.
4
+
5
+ import { FUNCTIONS } from './functions/index.js';
6
+ import { EMAIL_EXCLUDED_CATEGORIES, EMAIL_EXCLUDED_FUNCTIONS } from './constants.js';
7
+
8
+ /**
9
+ * Case-insensitive lookup: lowercase name -> function entry
10
+ */
11
+ export const functionLookup = new Map(FUNCTIONS.map((f) => [f.name.toLowerCase(), f]));
12
+
13
+ /**
14
+ * Set of lowercase function names for quick membership checks
15
+ */
16
+ export const functionNames = new Set(FUNCTIONS.map((f) => f.name.toLowerCase()));
17
+
18
+ // ── Canonical casing map ─────────────────────────────────────────────────────
19
+
20
+ /**
21
+ * Ordered list of canonical PascalCase function names
22
+ */
23
+ export const CANONICAL_FUNCTIONS = FUNCTIONS.map((f) => f.name);
24
+
25
+ /**
26
+ * Map from lowercase -> canonical PascalCase name
27
+ */
28
+ export const FUNCTION_CANONICAL_MAP = new Map(
29
+ CANONICAL_FUNCTIONS.map((name) => [name.toLowerCase(), name]),
30
+ );
31
+
32
+ // ── Deprecated functions ─────────────────────────────────────────────────────
33
+ // Deprecation metadata lives inline on each FUNCTIONS entry via the
34
+ // `deprecated`, `deprecatedReplacement`, and `deprecatedReason` fields. The
35
+ // lookup below is derived from those flags for consumers that need a quick
36
+ // name -> entry map of deprecated functions.
37
+
38
+ /**
39
+ * Case-insensitive lookup of deprecated functions: lowercase name -> function entry
40
+ */
41
+ export const deprecatedFunctionLookup = new Map(
42
+ FUNCTIONS.filter((f) => f.deprecated).map((f) => [f.name.toLowerCase(), f]),
43
+ );
44
+
45
+ /**
46
+ * Case-insensitive lookup of functions that resolve at runtime but have no known
47
+ * working invocation (`nonFunctionalAtRuntime`): lowercase name -> function entry.
48
+ * Every reached call aborts the page (e.g. a retired Classic feature), so callers
49
+ * can flag the call site. Kept separate from deprecation because these functions
50
+ * were never formally deprecated by Salesforce.
51
+ */
52
+ export const nonFunctionalFunctionLookup = new Map(
53
+ FUNCTIONS.filter((f) => f.nonFunctionalAtRuntime).map((f) => [f.name.toLowerCase(), f]),
54
+ );
55
+
56
+ // ── Email-context restrictions ───────────────────────────────────────────────
57
+
58
+ export function isEmailExcluded(functionName) {
59
+ const lower = functionName.toLowerCase();
60
+ if (EMAIL_EXCLUDED_FUNCTIONS.has(lower)) {
61
+ return true;
62
+ }
63
+ const entry = functionLookup.get(lower);
64
+ return entry ? EMAIL_EXCLUDED_CATEGORIES.has(entry.category) : false;
65
+ }
66
+
67
+ // ── Marketing Cloud Next (MCN) helpers ───────────────────────────────────────
68
+
69
+ /**
70
+ * Returns the API version from which this AMPscript function is supported in
71
+ * Marketing Cloud Next, or null if it is not supported in MCN.
72
+ *
73
+ * @param {string} name - AMPscript function name (case-insensitive).
74
+ * @returns {number | null} API version number (e.g. 67) or null.
75
+ */
76
+ export function getMcnApiVersion(name) {
77
+ return functionLookup.get(name.toLowerCase())?.mcnSince ?? null;
78
+ }
79
+
80
+ /**
81
+ * Returns true when the given AMPscript function is supported in Marketing
82
+ * Cloud Next (i.e. mcnSince is a non-null API version number).
83
+ *
84
+ * @param {string} name - AMPscript function name (case-insensitive).
85
+ * @returns {boolean} True when the function is supported in Marketing Cloud Next.
86
+ */
87
+ export function isMcnSupported(name) {
88
+ return getMcnApiVersion(name) !== null;
89
+ }
90
+
91
+ /**
92
+ * Returns the MCN behavioral difference notes for the given function, or null
93
+ * if there are no differences or the function is not MCN-supported.
94
+ *
95
+ * @param {string} name - AMPscript function name (case-insensitive).
96
+ * @returns {string | null} Behavioral difference notes, or null.
97
+ */
98
+ export function getMcnNotes(name) {
99
+ return functionLookup.get(name.toLowerCase())?.mcnNotes ?? null;
100
+ }