@zeyos/zx 5.5.0 → 5.7.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/CHANGELOG.md +210 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +711 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- package/dist/types/components/approval-card/approval-card.d.ts +596 -0
- package/dist/types/components/avatar/avatar.d.ts +91 -4
- package/dist/types/components/block-view/block-view.d.ts +205 -0
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +938 -0
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +17 -6
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- package/dist/types/components/run-status/run-status.d.ts +393 -0
- package/dist/types/components/run-trace/run-trace.d.ts +624 -0
- package/dist/types/components/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +179 -0
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +1 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +479 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +18 -1
- package/dist/types/internal/agent-model.d.ts +587 -0
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/highlight.d.ts +24 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/internal/presence-loop.d.ts +148 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +20505 -18748
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +2424 -134
- package/dist/zx.esm.js +46167 -28468
- package/dist/zx.esm.min.js +40 -8
- package/dist/zx.global.js +46167 -28468
- package/dist/zx.global.min.js +40 -8
- package/dist/zx.layered.css +17302 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +2057 -166
- package/docs/llms.md +1458 -58
- package/docs/llms.txt +38 -8
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.css +417 -0
- package/src/components/agent-thread/agent-thread.js +1670 -0
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.css +289 -0
- package/src/components/approval-card/approval-card.js +1378 -0
- package/src/components/avatar/avatar.css +56 -1
- package/src/components/avatar/avatar.js +148 -26
- package/src/components/block-view/block-view.css +300 -0
- package/src/components/block-view/block-view.js +524 -0
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +482 -0
- package/src/components/composer/composer.js +1815 -0
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +1 -1
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +29 -13
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- package/src/components/run-status/run-status.css +208 -0
- package/src/components/run-status/run-status.js +782 -0
- package/src/components/run-trace/run-trace.css +443 -0
- package/src/components/run-trace/run-trace.js +1209 -0
- package/src/components/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.css +208 -0
- package/src/components/source-list/source-list.js +358 -0
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +22 -2
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +519 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +18 -1
- package/src/internal/agent-model.js +488 -0
- package/src/internal/date-locale.js +11 -0
- package/src/internal/highlight.js +104 -0
- package/src/internal/json-patch.js +405 -0
- package/src/internal/presence-loop.js +343 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +11 -8
- package/styles/zx.layered.css +1 -0
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* A small syntax tokenizer for code an agent writes into an answer. It recognises comments,
|
|
4
|
+
* strings, numbers, and keywords — enough to make code readable, never enough to be an editor —
|
|
5
|
+
* and returns segments, never markup, so the caller builds text nodes and spans from them.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** @typedef {'comment'|'string'|'number'|'keyword'} TokenKind */
|
|
9
|
+
/** @typedef {{text: string, token: TokenKind|null}} CodeSegment */
|
|
10
|
+
|
|
11
|
+
/** A string in single, double, or back quotes; unterminated while it is still being streamed. */
|
|
12
|
+
const STRING = /'(?:[^'\\\n]|\\.)*'?|"(?:[^"\\\n]|\\.)*"?|`(?:[^`\\]|\\.)*`?/;
|
|
13
|
+
/** A number, digit separators included: `30_000`, `0.5`, `1e3`. */
|
|
14
|
+
const NUMBER = /\b\d[\d_]*(?:\.\d+)?(?:e[+-]?\d+)?\b/;
|
|
15
|
+
/** A name or a keyword. */
|
|
16
|
+
const WORD = /[A-Za-z_$][\w$]*/;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* What the tokenizer recognises in one language. Comments, strings, numbers, and words are
|
|
20
|
+
* matched in that order from left to right, so a quote inside a comment or a digit inside a name
|
|
21
|
+
* never starts a token of its own.
|
|
22
|
+
* @param {RegExp} comment Line or block comment.
|
|
23
|
+
* @param {string} keywords Space-separated, lower case for caseless languages.
|
|
24
|
+
* @param {{caseless?: boolean, string?: RegExp}} [options]
|
|
25
|
+
* @returns {{pattern: RegExp, keywords: Set<string>, caseless: boolean}}
|
|
26
|
+
*/
|
|
27
|
+
function grammar(comment, keywords, options = {}) {
|
|
28
|
+
const parts = [['comment', comment], ['string', options.string ?? STRING], ['number', NUMBER], ['word', WORD]];
|
|
29
|
+
return {
|
|
30
|
+
pattern: new RegExp(parts.map(([name, part]) => `(?<${name}>${/** @type {RegExp} */ (part).source})`).join('|'), 'g'),
|
|
31
|
+
keywords: new Set(keywords.split(' ')),
|
|
32
|
+
caseless: Boolean(options.caseless)
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const SCRIPT_KEYWORDS = 'async await break case catch class const continue debugger default delete do else export '
|
|
37
|
+
+ 'extends false finally for from function if import in instanceof let new null of return static super switch '
|
|
38
|
+
+ 'this throw true try typeof undefined var void while yield';
|
|
39
|
+
|
|
40
|
+
const GRAMMARS = Object.freeze({
|
|
41
|
+
javascript: grammar(/\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$)/, SCRIPT_KEYWORDS),
|
|
42
|
+
typescript: grammar(/\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$)/, `${SCRIPT_KEYWORDS} abstract as declare enum implements interface keyof `
|
|
43
|
+
+ 'namespace private protected public readonly type'),
|
|
44
|
+
json: grammar(/(?!)/, 'true false null', { string: /"(?:[^"\\\n]|\\.)*"?/ }),
|
|
45
|
+
sql: grammar(/--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)/, 'and as asc between by case count delete desc distinct else end exists from '
|
|
46
|
+
+ 'group having in inner insert interval into is join left limit not null on or order outer right select set sum '
|
|
47
|
+
+ 'then union update values when where with', { caseless: true, string: /'(?:[^'\n]|'')*'?/ }),
|
|
48
|
+
python: grammar(/#[^\n]*/, 'and as assert async await break class continue def del elif else except false finally for '
|
|
49
|
+
+ 'from global if import in is lambda none nonlocal not or pass raise return true try while with yield', { caseless: false }),
|
|
50
|
+
shell: grammar(/(?<!\S)#[^\n]*/, 'case do done elif else esac export fi for function if in local read return then until while'),
|
|
51
|
+
css: grammar(/\/\*[\s\S]*?(?:\*\/|$)/, 'important inherit initial none unset auto')
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
/** Language names an answer may use, mapped to the grammar that reads them. */
|
|
55
|
+
const ALIASES = Object.freeze({
|
|
56
|
+
js: 'javascript', javascript: 'javascript', mjs: 'javascript', jsx: 'javascript',
|
|
57
|
+
ts: 'typescript', typescript: 'typescript', tsx: 'typescript',
|
|
58
|
+
json: 'json',
|
|
59
|
+
sql: 'sql',
|
|
60
|
+
py: 'python', python: 'python',
|
|
61
|
+
sh: 'shell', bash: 'shell', shell: 'shell', zsh: 'shell',
|
|
62
|
+
css: 'css'
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Whether code in this language is coloured.
|
|
67
|
+
* @param {unknown} language
|
|
68
|
+
* @returns {boolean}
|
|
69
|
+
*/
|
|
70
|
+
export function isHighlighted(language) {
|
|
71
|
+
return Object.hasOwn(ALIASES, String(language ?? '').toLowerCase());
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Splits code into plain and coloured segments. An unknown language is one plain segment.
|
|
76
|
+
* Python's `True`/`None` and SQL's upper-case keywords are matched without regard to case.
|
|
77
|
+
* @param {unknown} language
|
|
78
|
+
* @param {unknown} source
|
|
79
|
+
* @returns {CodeSegment[]}
|
|
80
|
+
*/
|
|
81
|
+
export function highlight(language, source) {
|
|
82
|
+
const code = source == null ? '' : String(source);
|
|
83
|
+
const name = ALIASES[/** @type {keyof typeof ALIASES} */ (String(language ?? '').toLowerCase())];
|
|
84
|
+
const syntax = name ? GRAMMARS[/** @type {keyof typeof GRAMMARS} */ (name)] : null;
|
|
85
|
+
if (!syntax) return code ? [{ text: code, token: null }] : [];
|
|
86
|
+
const caseless = syntax.caseless || name === 'python';
|
|
87
|
+
/** @type {CodeSegment[]} */
|
|
88
|
+
const out = [];
|
|
89
|
+
let plain = 0;
|
|
90
|
+
for (const match of code.matchAll(syntax.pattern)) {
|
|
91
|
+
if (match[0] === '') continue;
|
|
92
|
+
const groups = /** @type {Record<string, string|undefined>} */ (match.groups);
|
|
93
|
+
/** @type {TokenKind|null} */
|
|
94
|
+
const token = groups.comment ? 'comment' : groups.string ? 'string' : groups.number ? 'number'
|
|
95
|
+
: groups.word && syntax.keywords.has(caseless ? groups.word.toLowerCase() : groups.word) ? 'keyword' : null;
|
|
96
|
+
if (!token) continue;
|
|
97
|
+
const start = Number(match.index);
|
|
98
|
+
if (start > plain) out.push({ text: code.slice(plain, start), token: null });
|
|
99
|
+
out.push({ text: match[0], token });
|
|
100
|
+
plain = start + match[0].length;
|
|
101
|
+
}
|
|
102
|
+
if (plain < code.length) out.push({ text: code.slice(plain), token: null });
|
|
103
|
+
return out;
|
|
104
|
+
}
|
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* JSON Pointer (RFC 6901) and JSON Patch (RFC 6902) over plain JSON values.
|
|
4
|
+
*
|
|
5
|
+
* Every function here is pure: a document handed in is never mutated, and a function that changes
|
|
6
|
+
* something returns a new document. Pointers may not walk through `__proto__`, `constructor` or
|
|
7
|
+
* `prototype`, so a pointer written by a model or a server can never reach an object's prototype.
|
|
8
|
+
*
|
|
9
|
+
* The module touches no DOM and imports nothing, so it runs unchanged in a browser and on a server.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** Segments refused anywhere in a pointer. */
|
|
13
|
+
const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
14
|
+
|
|
15
|
+
/** The six RFC 6902 operations. */
|
|
16
|
+
const OPERATIONS = new Set(['add', 'remove', 'replace', 'move', 'copy', 'test']);
|
|
17
|
+
|
|
18
|
+
/** An array index as RFC 6901 writes it: `0`, or digits without a leading zero. */
|
|
19
|
+
const ARRAY_INDEX = /^(?:0|[1-9][0-9]*)$/;
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Why a pointer or a patch operation could not be applied.
|
|
23
|
+
* - `invalid-pointer`: the pointer is not a string, or is not empty and does not start with `/`,
|
|
24
|
+
* or carries a `~` that is not `~0` or `~1`.
|
|
25
|
+
* - `forbidden-segment`: a segment is `__proto__`, `constructor` or `prototype`.
|
|
26
|
+
* - `not-a-container`: the path runs through a value that is neither an object nor an array.
|
|
27
|
+
* - `path-not-found`: the target, or its parent, does not exist.
|
|
28
|
+
* - `invalid-index`: an array segment is not an index, is out of range, or is `-` where nothing
|
|
29
|
+
* is appended.
|
|
30
|
+
* - `invalid-operation`: an operation is malformed or unknown, or moves a value into itself.
|
|
31
|
+
* - `test-failed`: a `test` operation's value differs from the document's.
|
|
32
|
+
* @typedef {'invalid-pointer'|'forbidden-segment'|'not-a-container'|'path-not-found'|'invalid-index'|'invalid-operation'|'test-failed'} JsonPatchErrorCode
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* One RFC 6902 operation. `value` is required by `add`, `replace` and `test`, `from` by `move`
|
|
37
|
+
* and `copy`. Other members are ignored, as the RFC asks.
|
|
38
|
+
* @typedef {Object} JsonPatchOperation
|
|
39
|
+
* @property {'add'|'remove'|'replace'|'move'|'copy'|'test'} op Operation name.
|
|
40
|
+
* @property {string} path RFC 6901 pointer to the target.
|
|
41
|
+
* @property {unknown} [value] Value to add, replace with, or test against.
|
|
42
|
+
* @property {string} [from] RFC 6901 pointer to the source of a `move` or `copy`.
|
|
43
|
+
*/
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The error every function in this module throws. `code` says what went wrong, `pointer` where,
|
|
47
|
+
* and `index` which operation of a patch failed (`-1` outside a patch).
|
|
48
|
+
*/
|
|
49
|
+
export class JsonPatchError extends Error {
|
|
50
|
+
/**
|
|
51
|
+
* @param {string} message Human-readable description.
|
|
52
|
+
* @param {JsonPatchErrorCode} code What went wrong.
|
|
53
|
+
* @param {string} [pointer=''] The pointer involved.
|
|
54
|
+
* @param {number} [index=-1] Position of the failing operation within a patch.
|
|
55
|
+
*/
|
|
56
|
+
constructor(message, code, pointer = '', index = -1) {
|
|
57
|
+
super(message);
|
|
58
|
+
this.name = 'JsonPatchError';
|
|
59
|
+
/** @type {JsonPatchErrorCode} */
|
|
60
|
+
this.code = code;
|
|
61
|
+
/** @type {string} */
|
|
62
|
+
this.pointer = pointer;
|
|
63
|
+
/** @type {number} */
|
|
64
|
+
this.index = index;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Splits an RFC 6901 pointer into its unescaped segments. `''` is the whole document and yields no
|
|
70
|
+
* segments; `'/'` yields one empty segment. `~1` becomes `/` and then `~0` becomes `~`, in that
|
|
71
|
+
* order, so `~01` reads as the two characters `~1`.
|
|
72
|
+
* @param {string} pointer RFC 6901 pointer.
|
|
73
|
+
* @returns {string[]}
|
|
74
|
+
* @throws {JsonPatchError} `invalid-pointer` when malformed, `forbidden-segment` for `__proto__`,
|
|
75
|
+
* `constructor` or `prototype`.
|
|
76
|
+
*/
|
|
77
|
+
export function parsePointer(pointer) {
|
|
78
|
+
if (typeof pointer !== 'string') throw new JsonPatchError('A pointer must be a string', 'invalid-pointer');
|
|
79
|
+
if (pointer === '') return [];
|
|
80
|
+
if (pointer[0] !== '/') {
|
|
81
|
+
throw new JsonPatchError(`A pointer must be empty or start with "/": ${pointer}`, 'invalid-pointer', pointer);
|
|
82
|
+
}
|
|
83
|
+
return pointer.slice(1).split('/').map((raw) => {
|
|
84
|
+
if (/~(?![01])/.test(raw)) {
|
|
85
|
+
throw new JsonPatchError(`A pointer may only escape "~0" and "~1": ${pointer}`, 'invalid-pointer', pointer);
|
|
86
|
+
}
|
|
87
|
+
const segment = raw.replace(/~1/g, '/').replace(/~0/g, '~');
|
|
88
|
+
if (FORBIDDEN_SEGMENTS.has(segment)) {
|
|
89
|
+
throw new JsonPatchError(`A pointer may not name "${segment}": ${pointer}`, 'forbidden-segment', pointer);
|
|
90
|
+
}
|
|
91
|
+
return segment;
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Joins segments into an RFC 6901 pointer, escaping `~` as `~0` and `/` as `~1`. The inverse of
|
|
97
|
+
* `parsePointer()`.
|
|
98
|
+
* @param {Array<string|number>} segments Unescaped segments.
|
|
99
|
+
* @returns {string}
|
|
100
|
+
*/
|
|
101
|
+
export function formatPointer(segments) {
|
|
102
|
+
return segments.map((segment) => `/${String(segment).replace(/~/g, '~0').replace(/\//g, '~1')}`).join('');
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Reads the value a pointer names. A path that does not exist, runs through a value that is not a
|
|
107
|
+
* container, or ends in `-` reads as `undefined` rather than throwing, so a binding to data that
|
|
108
|
+
* has not arrived yet is simply empty.
|
|
109
|
+
* @param {unknown} document JSON value to read from.
|
|
110
|
+
* @param {string} pointer RFC 6901 pointer.
|
|
111
|
+
* @returns {unknown} The value, or `undefined` when there is none.
|
|
112
|
+
* @throws {JsonPatchError} When the pointer itself is malformed or names a forbidden segment.
|
|
113
|
+
*/
|
|
114
|
+
export function getPointer(document, pointer) {
|
|
115
|
+
let current = document;
|
|
116
|
+
for (const segment of parsePointer(pointer)) {
|
|
117
|
+
if (Array.isArray(current)) {
|
|
118
|
+
if (!ARRAY_INDEX.test(segment)) return undefined;
|
|
119
|
+
const index = Number(segment);
|
|
120
|
+
if (index >= current.length) return undefined;
|
|
121
|
+
current = current[index];
|
|
122
|
+
} else if (isObject(current)) {
|
|
123
|
+
if (!Object.hasOwn(current, segment)) return undefined;
|
|
124
|
+
current = /** @type {Record<string, unknown>} */ (current)[segment];
|
|
125
|
+
} else {
|
|
126
|
+
return undefined;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return current;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Reports whether a pointer names an existing value, which `getPointer()` cannot tell from a
|
|
134
|
+
* missing one when the value read is `undefined`.
|
|
135
|
+
* @param {unknown} document JSON value to read from.
|
|
136
|
+
* @param {string} pointer RFC 6901 pointer.
|
|
137
|
+
* @returns {boolean}
|
|
138
|
+
* @throws {JsonPatchError} When the pointer itself is malformed or names a forbidden segment.
|
|
139
|
+
*/
|
|
140
|
+
export function hasPointer(document, pointer) {
|
|
141
|
+
let current = document;
|
|
142
|
+
for (const segment of parsePointer(pointer)) {
|
|
143
|
+
if (Array.isArray(current)) {
|
|
144
|
+
if (!ARRAY_INDEX.test(segment) || Number(segment) >= current.length) return false;
|
|
145
|
+
current = current[Number(segment)];
|
|
146
|
+
} else if (isObject(current)) {
|
|
147
|
+
if (!Object.hasOwn(current, segment)) return false;
|
|
148
|
+
current = /** @type {Record<string, unknown>} */ (current)[segment];
|
|
149
|
+
} else {
|
|
150
|
+
return false;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
return true;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Stores a value at a pointer and returns the new document: the simple "set" a data stream needs.
|
|
158
|
+
* An object member is created or replaced; an array element at an existing index is replaced, and
|
|
159
|
+
* one at the array's length or at `-` is appended. The empty pointer replaces the whole document.
|
|
160
|
+
* Every parent on the path must already exist. The value is copied in, never shared.
|
|
161
|
+
* @param {unknown} document JSON value to change. Not mutated.
|
|
162
|
+
* @param {string} pointer RFC 6901 pointer.
|
|
163
|
+
* @param {unknown} value JSON value to store.
|
|
164
|
+
* @returns {unknown} The new document.
|
|
165
|
+
* @throws {JsonPatchError} `not-a-container` when the path runs through a value that is not an
|
|
166
|
+
* object or array, `path-not-found` when a parent is missing, `invalid-index` for a bad array
|
|
167
|
+
* segment, or a pointer error.
|
|
168
|
+
*/
|
|
169
|
+
export function setPointer(document, pointer, value) {
|
|
170
|
+
const segments = parsePointer(pointer);
|
|
171
|
+
if (segments.length === 0) return cloneJson(value);
|
|
172
|
+
const root = cloneJson(document);
|
|
173
|
+
const { parent, key } = locateParent(root, segments, pointer);
|
|
174
|
+
if (Array.isArray(parent)) {
|
|
175
|
+
const index = key === '-' ? parent.length : arrayIndex(key, parent.length, pointer);
|
|
176
|
+
parent[index] = cloneJson(value);
|
|
177
|
+
} else {
|
|
178
|
+
/** @type {Record<string, unknown>} */ (parent)[key] = cloneJson(value);
|
|
179
|
+
}
|
|
180
|
+
return root;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Removes the value at a pointer and returns the new document. An array element is spliced out,
|
|
185
|
+
* so the elements after it move up.
|
|
186
|
+
* @param {unknown} document JSON value to change. Not mutated.
|
|
187
|
+
* @param {string} pointer RFC 6901 pointer to an existing value; not the empty pointer.
|
|
188
|
+
* @returns {unknown} The new document.
|
|
189
|
+
* @throws {JsonPatchError} `path-not-found` when nothing is there, `not-a-container` when the path
|
|
190
|
+
* runs through a value that is not an object or array, `invalid-operation` for the empty
|
|
191
|
+
* pointer, or a pointer error.
|
|
192
|
+
*/
|
|
193
|
+
export function removePointer(document, pointer) {
|
|
194
|
+
const root = cloneJson(document);
|
|
195
|
+
removeAt(root, parsePointer(pointer), pointer);
|
|
196
|
+
return root;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Applies an RFC 6902 patch and returns the new document. The input is never mutated, and the
|
|
201
|
+
* patch applies all or nothing: when any operation fails — a failing `test` included — the error
|
|
202
|
+
* is thrown and no partial result exists.
|
|
203
|
+
* @param {unknown} document JSON value to patch. Not mutated.
|
|
204
|
+
* @param {JsonPatchOperation[]} operations Operations, applied in order.
|
|
205
|
+
* @returns {unknown} The patched document.
|
|
206
|
+
* @throws {JsonPatchError} At the first failing operation; its `index` says which.
|
|
207
|
+
*/
|
|
208
|
+
export function applyPatch(document, operations) {
|
|
209
|
+
if (!Array.isArray(operations)) {
|
|
210
|
+
throw new JsonPatchError('A patch must be an array of operations', 'invalid-operation');
|
|
211
|
+
}
|
|
212
|
+
// One deep copy up front: every operation then works in place on a document nobody else holds.
|
|
213
|
+
let root = cloneJson(document);
|
|
214
|
+
operations.forEach((operation, index) => {
|
|
215
|
+
try {
|
|
216
|
+
root = applyOperation(root, operation);
|
|
217
|
+
} catch (error) {
|
|
218
|
+
if (error instanceof JsonPatchError) {
|
|
219
|
+
error.index = index;
|
|
220
|
+
error.message = `Operation ${index}: ${error.message}`;
|
|
221
|
+
}
|
|
222
|
+
throw error;
|
|
223
|
+
}
|
|
224
|
+
});
|
|
225
|
+
return root;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Applies one operation in place to a document this module owns, returning the root (which only
|
|
230
|
+
* changes when the operation targets the whole document).
|
|
231
|
+
* @param {unknown} root
|
|
232
|
+
* @param {JsonPatchOperation} operation
|
|
233
|
+
* @returns {unknown}
|
|
234
|
+
*/
|
|
235
|
+
function applyOperation(root, operation) {
|
|
236
|
+
if (!isObject(operation) || typeof operation.op !== 'string' || !OPERATIONS.has(operation.op)) {
|
|
237
|
+
throw new JsonPatchError('Unknown or missing "op"', 'invalid-operation');
|
|
238
|
+
}
|
|
239
|
+
const { op, path } = operation;
|
|
240
|
+
if (typeof path !== 'string') throw new JsonPatchError(`"${op}" needs a string "path"`, 'invalid-operation');
|
|
241
|
+
const segments = parsePointer(path);
|
|
242
|
+
const needsValue = op === 'add' || op === 'replace' || op === 'test';
|
|
243
|
+
if (needsValue && !Object.hasOwn(operation, 'value')) {
|
|
244
|
+
throw new JsonPatchError(`"${op}" needs a "value"`, 'invalid-operation', path);
|
|
245
|
+
}
|
|
246
|
+
const needsFrom = op === 'move' || op === 'copy';
|
|
247
|
+
if (needsFrom && typeof operation.from !== 'string') {
|
|
248
|
+
throw new JsonPatchError(`"${op}" needs a string "from"`, 'invalid-operation', path);
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
switch (op) {
|
|
252
|
+
case 'add':
|
|
253
|
+
return addAt(root, segments, path, cloneJson(operation.value));
|
|
254
|
+
case 'remove':
|
|
255
|
+
removeAt(root, segments, path);
|
|
256
|
+
return root;
|
|
257
|
+
case 'replace':
|
|
258
|
+
if (segments.length === 0) return cloneJson(operation.value);
|
|
259
|
+
if (!hasPointer(root, path)) throw new JsonPatchError(`Nothing to replace at ${path}`, 'path-not-found', path);
|
|
260
|
+
return addAt(root, segments, path, cloneJson(operation.value), true);
|
|
261
|
+
case 'test': {
|
|
262
|
+
if (!hasPointer(root, path)) throw new JsonPatchError(`Nothing to test at ${path}`, 'path-not-found', path);
|
|
263
|
+
if (!jsonEqual(getPointer(root, path), operation.value)) {
|
|
264
|
+
throw new JsonPatchError(`Test failed at ${path}`, 'test-failed', path);
|
|
265
|
+
}
|
|
266
|
+
return root;
|
|
267
|
+
}
|
|
268
|
+
default: {
|
|
269
|
+
const from = /** @type {string} */ (operation.from);
|
|
270
|
+
const source = parsePointer(from);
|
|
271
|
+
if (!hasPointer(root, from)) throw new JsonPatchError(`Nothing to ${op} at ${from}`, 'path-not-found', from);
|
|
272
|
+
if (op === 'copy') return addAt(root, segments, path, cloneJson(getPointer(root, from)));
|
|
273
|
+
if (from === path) return root;
|
|
274
|
+
if (source.length < segments.length && source.every((segment, index) => segment === segments[index])) {
|
|
275
|
+
throw new JsonPatchError(`Cannot move ${from} into its own child ${path}`, 'invalid-operation', path);
|
|
276
|
+
}
|
|
277
|
+
const value = getPointer(root, from);
|
|
278
|
+
removeAt(root, source, from);
|
|
279
|
+
return addAt(root, segments, path, value);
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* RFC 6902 `add` (or, with `replace`, an in-place overwrite) on a document this module owns.
|
|
286
|
+
* @param {unknown} root @param {string[]} segments @param {string} pointer @param {unknown} value
|
|
287
|
+
* @param {boolean} [replace=false]
|
|
288
|
+
* @returns {unknown} The root.
|
|
289
|
+
*/
|
|
290
|
+
function addAt(root, segments, pointer, value, replace = false) {
|
|
291
|
+
if (segments.length === 0) return value;
|
|
292
|
+
const { parent, key } = locateParent(root, segments, pointer);
|
|
293
|
+
if (Array.isArray(parent)) {
|
|
294
|
+
if (replace) parent[arrayIndex(key, parent.length - 1, pointer)] = value;
|
|
295
|
+
else if (key === '-') parent.push(value);
|
|
296
|
+
else parent.splice(arrayIndex(key, parent.length, pointer), 0, value);
|
|
297
|
+
} else {
|
|
298
|
+
/** @type {Record<string, unknown>} */ (parent)[key] = value;
|
|
299
|
+
}
|
|
300
|
+
return root;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** @param {unknown} root @param {string[]} segments @param {string} pointer @returns {void} */
|
|
304
|
+
function removeAt(root, segments, pointer) {
|
|
305
|
+
if (segments.length === 0) {
|
|
306
|
+
throw new JsonPatchError('The whole document cannot be removed', 'invalid-operation', pointer);
|
|
307
|
+
}
|
|
308
|
+
const { parent, key } = locateParent(root, segments, pointer);
|
|
309
|
+
if (Array.isArray(parent)) {
|
|
310
|
+
if (!ARRAY_INDEX.test(key) || Number(key) >= parent.length) {
|
|
311
|
+
throw new JsonPatchError(`Nothing to remove at ${pointer}`, 'path-not-found', pointer);
|
|
312
|
+
}
|
|
313
|
+
parent.splice(Number(key), 1);
|
|
314
|
+
return;
|
|
315
|
+
}
|
|
316
|
+
if (!Object.hasOwn(/** @type {object} */ (parent), key)) {
|
|
317
|
+
throw new JsonPatchError(`Nothing to remove at ${pointer}`, 'path-not-found', pointer);
|
|
318
|
+
}
|
|
319
|
+
delete /** @type {Record<string, unknown>} */ (parent)[key];
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* Walks to the container holding a pointer's last segment.
|
|
324
|
+
* @param {unknown} root @param {string[]} segments @param {string} pointer
|
|
325
|
+
* @returns {{parent: object, key: string}}
|
|
326
|
+
*/
|
|
327
|
+
function locateParent(root, segments, pointer) {
|
|
328
|
+
let current = root;
|
|
329
|
+
for (let step = 0; step < segments.length - 1; step += 1) {
|
|
330
|
+
const segment = segments[step];
|
|
331
|
+
const at = formatPointer(segments.slice(0, step + 1));
|
|
332
|
+
if (Array.isArray(current)) {
|
|
333
|
+
if (!ARRAY_INDEX.test(segment) || Number(segment) >= current.length) {
|
|
334
|
+
throw new JsonPatchError(`No array element at ${at}`, 'path-not-found', pointer);
|
|
335
|
+
}
|
|
336
|
+
current = current[Number(segment)];
|
|
337
|
+
} else if (isObject(current)) {
|
|
338
|
+
if (!Object.hasOwn(current, segment)) throw new JsonPatchError(`Nothing at ${at}`, 'path-not-found', pointer);
|
|
339
|
+
current = /** @type {Record<string, unknown>} */ (current)[segment];
|
|
340
|
+
} else {
|
|
341
|
+
throw new JsonPatchError(`The path runs through a value that is not an object at ${at}`,
|
|
342
|
+
'not-a-container', pointer);
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
if (!Array.isArray(current) && !isObject(current)) {
|
|
346
|
+
const at = formatPointer(segments.slice(0, -1)) || '(the document)';
|
|
347
|
+
throw new JsonPatchError(`The path runs through a value that is not an object at ${at}`,
|
|
348
|
+
'not-a-container', pointer);
|
|
349
|
+
}
|
|
350
|
+
return { parent: /** @type {object} */ (current), key: segments[segments.length - 1] };
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* @param {string} key @param {number} max Highest index allowed. @param {string} pointer
|
|
355
|
+
* @returns {number}
|
|
356
|
+
*/
|
|
357
|
+
function arrayIndex(key, max, pointer) {
|
|
358
|
+
if (!ARRAY_INDEX.test(key) || Number(key) > max) {
|
|
359
|
+
throw new JsonPatchError(`Not a usable array index at ${pointer}`, 'invalid-index', pointer);
|
|
360
|
+
}
|
|
361
|
+
return Number(key);
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/** @param {unknown} value @returns {value is Record<string, unknown>} */
|
|
365
|
+
function isObject(value) {
|
|
366
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Deep-copies a JSON value. Members are defined rather than assigned, so a member that happens to
|
|
371
|
+
* be called `__proto__` stays data and never becomes a prototype.
|
|
372
|
+
* @param {unknown} value
|
|
373
|
+
* @returns {any}
|
|
374
|
+
*/
|
|
375
|
+
function cloneJson(value) {
|
|
376
|
+
if (Array.isArray(value)) return value.map(cloneJson);
|
|
377
|
+
if (isObject(value)) {
|
|
378
|
+
/** @type {Record<string, unknown>} */
|
|
379
|
+
const copy = {};
|
|
380
|
+
for (const key of Object.keys(value)) {
|
|
381
|
+
Object.defineProperty(copy, key, { value: cloneJson(value[key]), enumerable: true, writable: true, configurable: true });
|
|
382
|
+
}
|
|
383
|
+
return copy;
|
|
384
|
+
}
|
|
385
|
+
return value;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* JSON equality as RFC 6902 `test` defines it: same type, numbers by value, strings by code
|
|
390
|
+
* points, arrays element by element in order, objects by the same members regardless of order.
|
|
391
|
+
* @param {unknown} a @param {unknown} b @returns {boolean}
|
|
392
|
+
*/
|
|
393
|
+
export function jsonEqual(a, b) {
|
|
394
|
+
if (a === b) return true;
|
|
395
|
+
if (Array.isArray(a) || Array.isArray(b)) {
|
|
396
|
+
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
|
|
397
|
+
return a.every((entry, index) => jsonEqual(entry, b[index]));
|
|
398
|
+
}
|
|
399
|
+
if (isObject(a) && isObject(b)) {
|
|
400
|
+
const keys = Object.keys(a);
|
|
401
|
+
if (keys.length !== Object.keys(b).length) return false;
|
|
402
|
+
return keys.every((key) => Object.hasOwn(b, key) && jsonEqual(a[key], b[key]));
|
|
403
|
+
}
|
|
404
|
+
return false;
|
|
405
|
+
}
|