ampscript-data 3.1.1 → 3.2.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.
Files changed (3) hide show
  1. package/README.md +45 -0
  2. package/package.json +1 -1
  3. package/src/index.js +134 -26
package/README.md CHANGED
@@ -32,6 +32,7 @@ import {
32
32
  isMcnSupported,
33
33
  getMcnApiVersion,
34
34
  getMcnNotes,
35
+ VERIFICATION_BLOCKED_REASONS,
35
36
  } from 'ampscript-data';
36
37
  ```
37
38
 
@@ -61,6 +62,50 @@ for (const fn of FUNCTIONS) {
61
62
  }
62
63
  ```
63
64
 
65
+ #### Optional: `validArities`
66
+
67
+ 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:
68
+
69
+ ```js
70
+ import { functionLookup } from 'ampscript-data';
71
+
72
+ const entry = functionLookup.get('somefunction');
73
+ if (entry.validArities) {
74
+ // e.g. minArgs: 1, maxArgs: 6, validArities: [1, 6] — 2-5 arguments are invalid
75
+ const isValidCall = entry.validArities.includes(argumentCount);
76
+ }
77
+ ```
78
+
79
+ 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.
80
+
81
+ #### Optional: verification state
82
+
83
+ | Field | Type | Description |
84
+ |---|---|---|
85
+ | `isConfirmed` | `boolean` | `true` when the behavior was verified against the live AMPscript engine; absent means never checked |
86
+ | `verificationBlocked` | `boolean` | `true` when verification was attempted but could not complete; requires `isConfirmed: false` and a `verificationBlockedReason` |
87
+ | `verificationBlockedReason` | `string` | One of `VERIFICATION_BLOCKED_REASONS`; only valid together with `verificationBlocked: true` |
88
+ | `differsFromOfficialDocs` | `boolean` | `true` when the verified runtime behavior contradicts the official Salesforce reference; requires `officialDocsNote` |
89
+ | `officialDocsNote` | `string` | What the official docs claim, what the runtime actually did, and what was tried |
90
+
91
+ ### `VERIFICATION_BLOCKED_REASONS`
92
+
93
+ A frozen array of the blocker categories that may be used as `verificationBlockedReason`:
94
+
95
+ ```js
96
+ import { VERIFICATION_BLOCKED_REASONS } from 'ampscript-data';
97
+ // ['no-working-invocation', 'needs-auth-context', 'no-test-data',
98
+ // 'classic-only-no-assets', 'destructive-unsafe']
99
+ ```
100
+
101
+ | Value | Meaning |
102
+ |---|---|
103
+ | `no-working-invocation` | Probing found no invocation shape that works |
104
+ | `needs-auth-context` | Requires an authenticated / session / subscriber state the probe context cannot supply |
105
+ | `no-test-data` | Requires pre-existing data or an integration not provisioned on the BU |
106
+ | `classic-only-no-assets` | Only works with classic (legacy) assets and none exist to test against |
107
+ | `destructive-unsafe` | Cannot be exercised without unacceptable side effects |
108
+
64
109
  ### `functionLookup`
65
110
 
66
111
  A `Map<string, FunctionEntry>` keyed by lowercase function name for O(1) lookups:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ampscript-data",
3
- "version": "3.1.1",
3
+ "version": "3.2.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",
package/src/index.js CHANGED
@@ -5,10 +5,54 @@
5
5
  * - prettier-plugin-sfmc (casing normalization)
6
6
  * - eslint-plugin-sfmc (unknown-function detection, arity validation)
7
7
  * - vscode-sfmc-language (completions, hover, diagnostics)
8
+ *
9
+ * Optional verification-state fields on a FUNCTIONS entry:
10
+ * - isConfirmed?: boolean — true when the entry's behavior was verified against the
11
+ * live AMPscript engine. Absent means "never checked".
12
+ * - verificationBlocked?: boolean — true when a runtime verification was ATTEMPTED but
13
+ * could not complete for a concrete technical/environmental reason (no working
14
+ * invocation, missing auth/session context, absent test data). This is a THIRD state,
15
+ * distinct from both "verified" (isConfirmed: true) and "never checked" (neither flag
16
+ * set). When true, isConfirmed MUST be explicitly false and verificationBlockedReason
17
+ * MUST name the blocker category. The concrete, human-readable detail (error text,
18
+ * what was tried) belongs in officialDocsNote, not in the enum value.
19
+ * - verificationBlockedReason?: string — REQUIRED whenever verificationBlocked is true;
20
+ * one of the VERIFICATION_BLOCKED_REASONS enum values. Never set on its own.
21
+ * - differsFromOfficialDocs?: boolean — true when the verified runtime behavior contradicts
22
+ * the official Salesforce reference. Requires officialDocsNote to spell out the
23
+ * difference.
24
+ * - officialDocsNote?: string — human-readable evidence: what the official docs claim, what
25
+ * the runtime actually did, and what was tried.
8
26
  */
9
27
 
10
28
  const INF = Infinity;
11
29
 
30
+ // ── Verification-blocked reasons ─────────────────────────────────────────────
31
+ // Fixed enum of concrete technical/environmental reasons why a runtime verification
32
+ // was ATTEMPTED but could not complete. Set on an entry as `verificationBlockedReason`
33
+ // together with `verificationBlocked: true` and `isConfirmed: false`. The specific
34
+ // evidence (error text, invocation shapes tried) belongs in `officialDocsNote`, not here.
35
+ //
36
+ // - no-working-invocation probing found no invocation shape that works; document
37
+ // exactly what was tried in officialDocsNote.
38
+ // - needs-auth-context requires an authenticated / session / subscriber state that
39
+ // the probe context (e.g. a plain CloudPage) cannot supply
40
+ // - no-test-data requires pre-existing data or an integration that is not
41
+ // provisioned on the BU
42
+ // - classic-only-no-assets only works with classic (legacy) assets and none exist
43
+ // on the BU to test against
44
+ // - destructive-unsafe cannot be exercised without unacceptable side effects
45
+ /**
46
+ @type {readonly string[]}
47
+ */
48
+ export const VERIFICATION_BLOCKED_REASONS = Object.freeze([
49
+ 'no-working-invocation',
50
+ 'needs-auth-context',
51
+ 'no-test-data',
52
+ 'classic-only-no-assets',
53
+ 'destructive-unsafe',
54
+ ]);
55
+
12
56
  // ── Function catalog ─────────────────────────────────────────────────────────
13
57
 
14
58
  /**
@@ -25,7 +69,16 @@ const INF = Infinity;
25
69
  * Param naming convention for variadic functions: the first required occurrence of a
26
70
  * group member is `<base>1` and the repeating occurrence is `<base>N` (with `optional`).
27
71
  *
28
- @type {{name: string, mcnSince: number | null, mcnNotes: string | null, handlebarsEquivalent?: string | null, mcnHandlebarsGap?: boolean, docUrl?: string, guideUrl?: string, minArgs: number, maxArgs: number, category: string, description: string, params: {name: string, description: string, type?: string, enum?: (string | number)[], optional?: boolean, default?: string | number | boolean}[], returnType?: string, returnDescription?: string, returnEnum?: (string | number)[], syntax?: string, example?: string, repeat?: {startIndex: number, groupSize: number, minGroups: number, countParam?: string}[], deprecated?: boolean, deprecatedReplacement?: string, deprecatedReason?: string}[]} */
72
+ * `validArities` (OPTIONAL): exact set of permitted argument counts for a DISCONTINUOUS
73
+ * OVERLOAD, where a contiguous `minArgs..maxArgs` range would wrongly accept intermediate
74
+ * counts. When present, a call is valid only when its argument count is within
75
+ * [minArgs, maxArgs] AND a member of this array. The array MUST be strictly ascending
76
+ * integers, and both `minArgs` and `maxArgs` MUST be members (so `validArities[0] === minArgs`
77
+ * and the last element `=== maxArgs`). Example shape: a function that accepts exactly 1 or 6
78
+ * arguments (2-5 fail) would set `minArgs: 1, maxArgs: 6, validArities: [1, 6]`.
79
+ * Absent → behavior is a pure contiguous range. No AMPscript function currently needs it.
80
+ *
81
+ @type {{name: string, mcnSince: number | null, mcnNotes: string | null, handlebarsEquivalent?: string | null, mcnHandlebarsGap?: boolean, docUrl?: string, guideUrl?: string, minArgs: number, maxArgs: number, validArities?: number[], category: string, description: string, params: {name: string, description: string, type?: string, enum?: (string | number)[], optional?: boolean, default?: string | number | boolean}[], returnType?: string, returnDescription?: string, returnEnum?: (string | number)[], syntax?: string, example?: string, repeat?: {startIndex: number, groupSize: number, minGroups: number, countParam?: string}[], deprecated?: boolean, deprecatedReplacement?: string, deprecatedReason?: string, isConfirmed?: boolean, verificationBlocked?: boolean, verificationBlockedReason?: string, differsFromOfficialDocs?: boolean, officialDocsNote?: string}[]} */
29
82
  export const FUNCTIONS = [
30
83
  {
31
84
  name: 'Add',
@@ -39,13 +92,15 @@ export const FUNCTIONS = [
39
92
  category: 'Math',
40
93
  description: 'Computes the sum of two numeric values.',
41
94
  params: [
42
- { name: 'number1', description: 'First operand', type: 'number' },
43
- { name: 'number2', description: 'Second operand', type: 'number' },
95
+ { name: 'number1', description: 'First operand', type: 'string|number' },
96
+ { name: 'number2', description: 'Second operand', type: 'string|number' },
44
97
  ],
45
98
  returnType: 'number',
46
99
  returnDescription: 'The numeric sum of the two operands.',
47
100
  syntax: 'Add(number1, number2)',
48
101
  example: '%%=Add(15, 27)=%%',
102
+ isConfirmed: true,
103
+ differsFromOfficialDocs: false,
49
104
  },
50
105
  {
51
106
  name: 'AddMscrmListMember',
@@ -811,18 +866,30 @@ export const FUNCTIONS = [
811
866
  mcnNotes: null,
812
867
  docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-string/mc-ampscript-reference-string-concat.html',
813
868
  guideUrl: 'https://ampscript.guide/concat/',
814
- minArgs: 2,
869
+ minArgs: 1,
815
870
  maxArgs: INF,
871
+ isConfirmed: true,
872
+ differsFromOfficialDocs: false,
816
873
  category: 'String',
817
874
  description: 'Concatenates two or more string values.',
818
875
  params: [
819
- { name: 'string1', description: 'First string', type: 'string' },
820
- { name: 'string2', description: 'Second string', type: 'string' },
821
- { name: 'stringN', description: 'Additional string', type: 'string', optional: true },
876
+ { name: 'string1', description: 'First string', type: 'string|number|date' },
877
+ {
878
+ name: 'string2',
879
+ description: 'Second string',
880
+ type: 'string|number|date',
881
+ optional: true,
882
+ },
883
+ {
884
+ name: 'stringN',
885
+ description: 'Additional string',
886
+ type: 'string|number|date',
887
+ optional: true,
888
+ },
822
889
  ],
823
890
  returnType: 'string',
824
891
  returnDescription: 'The concatenation of all supplied values as a single string.',
825
- repeat: [{ startIndex: 0, groupSize: 1, minGroups: 2 }],
892
+ repeat: [{ startIndex: 0, groupSize: 1, minGroups: 1 }],
826
893
  syntax: 'Concat(string1, string2[, stringN, ...])',
827
894
  example: "%%=Concat('Hello', ' ', 'World')=%%",
828
895
  },
@@ -1675,13 +1742,16 @@ export const FUNCTIONS = [
1675
1742
  category: 'Math',
1676
1743
  description: 'Divides the first number by the second.',
1677
1744
  params: [
1678
- { name: 'dividend', description: 'Number to divide', type: 'number' },
1679
- { name: 'divisor', description: 'Number to divide by', type: 'number' },
1745
+ { name: 'dividend', description: 'Number to divide', type: 'string|number' },
1746
+ { name: 'divisor', description: 'Number to divide by', type: 'string|number' },
1680
1747
  ],
1681
1748
  returnType: 'number',
1682
- returnDescription: 'The quotient of the two operands.',
1749
+ returnDescription:
1750
+ 'The quotient of the two operands. A zero divisor does not raise an error: a non-zero dividend yields the infinity symbol and a zero dividend yields NaN, so guard against a zero divisor before rendering the result.',
1683
1751
  syntax: 'Divide(dividend, divisor)',
1684
1752
  example: '%%=Divide(100, 4)=%%',
1753
+ isConfirmed: true,
1754
+ differsFromOfficialDocs: false,
1685
1755
  },
1686
1756
  {
1687
1757
  name: 'Domain',
@@ -3087,11 +3157,20 @@ export const FUNCTIONS = [
3087
3157
  guideUrl: 'https://ampscript.guide/length/',
3088
3158
  minArgs: 1,
3089
3159
  maxArgs: 1,
3160
+ isConfirmed: true,
3161
+ differsFromOfficialDocs: false,
3090
3162
  category: 'String',
3091
3163
  description: 'Returns the number of characters in a string.',
3092
- params: [{ name: 'sourceString', description: 'String to measure', type: 'string' }],
3164
+ params: [
3165
+ {
3166
+ name: 'sourceString',
3167
+ description: 'String to measure',
3168
+ type: 'string|number|date',
3169
+ },
3170
+ ],
3093
3171
  returnType: 'number',
3094
- returnDescription: 'The number of characters in the string.',
3172
+ returnDescription:
3173
+ 'The number of UTF-16 code units in the string, so characters outside the Basic Multilingual Plane (such as emoji) count as 2.',
3095
3174
  syntax: 'Length(sourceString)',
3096
3175
  example: "%%=Length('Hello')=%%",
3097
3176
  },
@@ -3407,9 +3486,17 @@ export const FUNCTIONS = [
3407
3486
  guideUrl: 'https://ampscript.guide/lowercase/',
3408
3487
  minArgs: 1,
3409
3488
  maxArgs: 1,
3489
+ isConfirmed: true,
3490
+ differsFromOfficialDocs: false,
3410
3491
  category: 'String',
3411
3492
  description: 'Converts a string to all lowercase characters.',
3412
- params: [{ name: 'sourceString', description: 'String to convert', type: 'string' }],
3493
+ params: [
3494
+ {
3495
+ name: 'sourceString',
3496
+ description: 'String to convert',
3497
+ type: 'string|number|date',
3498
+ },
3499
+ ],
3413
3500
  returnType: 'string',
3414
3501
  returnDescription: 'The string converted to lower case.',
3415
3502
  syntax: 'Lowercase(sourceString)',
@@ -3526,13 +3613,16 @@ export const FUNCTIONS = [
3526
3613
  description:
3527
3614
  'Returns the remainder after dividing the first number by the second (modulo).',
3528
3615
  params: [
3529
- { name: 'dividend', description: 'Number to divide', type: 'number' },
3530
- { name: 'divisor', description: 'Number to divide by', type: 'number' },
3616
+ { name: 'dividend', description: 'Number to divide', type: 'string|number' },
3617
+ { name: 'divisor', description: 'Number to divide by', type: 'string|number' },
3531
3618
  ],
3532
3619
  returnType: 'number',
3533
- returnDescription: 'The remainder after dividing the first number by the second.',
3620
+ returnDescription:
3621
+ 'The remainder after dividing the first number by the second. The result takes the sign of the dividend, and a divisor of 0 yields NaN instead of raising an error.',
3534
3622
  syntax: 'Mod(dividend, divisor)',
3535
3623
  example: '%%=Mod(10, 3)=%%',
3624
+ isConfirmed: true,
3625
+ differsFromOfficialDocs: false,
3536
3626
  },
3537
3627
  {
3538
3628
  name: 'Msg',
@@ -3570,13 +3660,15 @@ export const FUNCTIONS = [
3570
3660
  category: 'Math',
3571
3661
  description: 'Computes the product of two numeric values.',
3572
3662
  params: [
3573
- { name: 'number1', description: 'First operand', type: 'number' },
3574
- { name: 'number2', description: 'Second operand', type: 'number' },
3663
+ { name: 'number1', description: 'First operand', type: 'string|number' },
3664
+ { name: 'number2', description: 'Second operand', type: 'string|number' },
3575
3665
  ],
3576
3666
  returnType: 'number',
3577
3667
  returnDescription: 'The product of the two operands.',
3578
3668
  syntax: 'Multiply(number1, number2)',
3579
3669
  example: '%%=Multiply(5, 3)=%%',
3670
+ isConfirmed: true,
3671
+ differsFromOfficialDocs: false,
3580
3672
  },
3581
3673
  {
3582
3674
  name: 'Noun',
@@ -3783,15 +3875,20 @@ export const FUNCTIONS = [
3783
3875
  minArgs: 2,
3784
3876
  maxArgs: 2,
3785
3877
  category: 'Math',
3786
- description: 'Returns a random integer between the two specified values (inclusive).',
3878
+ description:
3879
+ 'Returns a random integer between the two specified values (inclusive). Both bounds must be whole numbers; a decimal bound aborts the page. The bounds may be supplied in either order.',
3787
3880
  params: [
3788
- { name: 'min', description: 'Lower bound (inclusive)', type: 'number' },
3789
- { name: 'max', description: 'Upper bound (inclusive)', type: 'number' },
3881
+ { name: 'min', description: 'Lower bound (inclusive)', type: 'string|number' },
3882
+ { name: 'max', description: 'Upper bound (inclusive)', type: 'string|number' },
3790
3883
  ],
3791
3884
  returnType: 'number',
3792
3885
  returnDescription: 'A random whole number within the supplied range.',
3793
3886
  syntax: 'Random(min, max)',
3794
3887
  example: '%%=Random(1, 100)=%%',
3888
+ isConfirmed: true,
3889
+ differsFromOfficialDocs: true,
3890
+ officialDocsNote:
3891
+ 'The official reference states the bounds may be decimal numbers. On the child QA BU (MID 518005426) every decimal bound aborted the CloudPage with HTTP 422 — Random(1.2,1.8), Random(1,2.5), Random(1.0,3.0) and the quoted form Random("1.5","3.5") all failed, while the equivalent whole-number and numeric-string calls returned values normally. The same decimal calls also aborted on the parent BU (MID 7281698), so this is not a child-BU limitation. Only whole-number bounds are usable at runtime.',
3795
3892
  },
3796
3893
  {
3797
3894
  name: 'RatingStars',
@@ -4397,13 +4494,15 @@ export const FUNCTIONS = [
4397
4494
  category: 'Math',
4398
4495
  description: 'Computes the difference between two numeric values.',
4399
4496
  params: [
4400
- { name: 'minuend', description: 'Value to subtract from', type: 'number' },
4401
- { name: 'subtrahend', description: 'Value to subtract', type: 'number' },
4497
+ { name: 'minuend', description: 'Value to subtract from', type: 'string|number' },
4498
+ { name: 'subtrahend', description: 'Value to subtract', type: 'string|number' },
4402
4499
  ],
4403
4500
  returnType: 'number',
4404
4501
  returnDescription: 'The difference of the two operands.',
4405
4502
  syntax: 'Subtract(minuend, subtrahend)',
4406
4503
  example: '%%=Subtract(50, 15)=%%',
4504
+ isConfirmed: true,
4505
+ differsFromOfficialDocs: false,
4407
4506
  },
4408
4507
  {
4409
4508
  name: 'SystemDateToLocalDate',
@@ -4749,9 +4848,18 @@ export const FUNCTIONS = [
4749
4848
  guideUrl: 'https://ampscript.guide/uppercase/',
4750
4849
  minArgs: 1,
4751
4850
  maxArgs: 1,
4851
+ isConfirmed: true,
4852
+ differsFromOfficialDocs: false,
4752
4853
  category: 'String',
4753
- description: 'Converts a string to all uppercase characters.',
4754
- params: [{ name: 'sourceString', description: 'String to convert', type: 'string' }],
4854
+ description:
4855
+ 'Converts a string to all uppercase characters. The German sharp s remains unchanged rather than expanding to SS.',
4856
+ params: [
4857
+ {
4858
+ name: 'sourceString',
4859
+ description: 'String to convert',
4860
+ type: 'string|number|date',
4861
+ },
4862
+ ],
4755
4863
  returnType: 'string',
4756
4864
  returnDescription: 'The string converted to upper case.',
4757
4865
  syntax: 'Uppercase(sourceString)',