@deviltea/widget-core 0.0.3 → 0.0.4
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 +32 -4
- package/dist/index.d.mts +12 -1
- package/dist/index.mjs +37 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -273,10 +273,38 @@ subscribers. `failure.code` is one of:
|
|
|
273
273
|
before any operation is evaluated.
|
|
274
274
|
- An operation failure `{ code, operationIndex, message }`, where `code` is
|
|
275
275
|
`invalid-path`, `path-not-found`, `path-not-traversable`,
|
|
276
|
-
`invalid-array-index`, `invalid-move-target`, `test-failed`,
|
|
277
|
-
`source-access-failed`, and `operationIndex`
|
|
278
|
-
position in the patch. A failed patch leaves the
|
|
279
|
-
unchanged.
|
|
276
|
+
`invalid-array-index`, `invalid-move-target`, `test-failed`,
|
|
277
|
+
`json-incompatible-value`, or `source-access-failed`, and `operationIndex`
|
|
278
|
+
is the failing operation's position in the patch. A failed patch leaves the
|
|
279
|
+
committed source and revision unchanged.
|
|
280
|
+
|
|
281
|
+
| `code` | Meaning |
|
|
282
|
+
| --- | --- |
|
|
283
|
+
| `invalid-path` | malformed path or operation shape |
|
|
284
|
+
| `path-not-found` | the path does not identify an existing location |
|
|
285
|
+
| `path-not-traversable` | the path passes through a non-traversable value |
|
|
286
|
+
| `invalid-array-index` | an Array parent was addressed by anything other than an in-bounds canonical index (see below) |
|
|
287
|
+
| `invalid-move-target` | a `move` into its own descendant |
|
|
288
|
+
| `test-failed` | a `test` operand did not match the addressed value |
|
|
289
|
+
| `json-incompatible-value` | an `add`/`replace`/`test` `value` is outside Core's JSON domain (missing or `undefined`, functions, `bigint`, symbols, `NaN`/`±Infinity`, cycles, non-plain prototypes, sparse or extra-property Arrays, accessors, symbol keys, or reflection that throws); checked after path parsing and before the operation is evaluated |
|
|
290
|
+
| `source-access-failed` | unsafe access to the *source* material only |
|
|
291
|
+
|
|
292
|
+
Three edge semantics apply to every operation:
|
|
293
|
+
|
|
294
|
+
- **Arrays have only index members.** After path normalization, any segment on
|
|
295
|
+
an Array parent that is not a canonical index (`'length'`, `'foo'`, `'01'`, or a
|
|
296
|
+
structured `'-'`) fails `invalid-array-index`, at every position (traversal,
|
|
297
|
+
target, and `from`) and in both path forms. Append remains JSON-Pointer-only
|
|
298
|
+
(`/items/-`); a structured `'-'` never appends and is an ordinary key on
|
|
299
|
+
objects. Non-index properties already present on a recovery Array are repaired
|
|
300
|
+
by replacing that Array or an ancestor.
|
|
301
|
+
- **Numbers compare by SameValueZero.** `test` and no-op detection treat `0` and
|
|
302
|
+
`-0` as equal, so replacing `0` with `-0` (or the reverse) returns
|
|
303
|
+
`{ ok: true, changed: false }` and the source keeps its original value.
|
|
304
|
+
Explicit `add`/`replace` operands are copied with `-0` written as `+0` at
|
|
305
|
+
every depth; `copy`/`move` relocate existing material unchanged.
|
|
306
|
+
- **Operands must be JSON values.** A non-JSON operand fails with
|
|
307
|
+
`json-incompatible-value`, not `source-access-failed`.
|
|
280
308
|
|
|
281
309
|
`document.subscribe(listener)` registers `listener` and returns an idempotent
|
|
282
310
|
unsubscribe function. The listener is not called on subscription; it receives
|
package/dist/index.d.mts
CHANGED
|
@@ -25,8 +25,19 @@ type SourcePatchOperation = {
|
|
|
25
25
|
readonly path: SourcePath;
|
|
26
26
|
readonly value: JsonValue;
|
|
27
27
|
};
|
|
28
|
+
/**
|
|
29
|
+
* An RFC 6902-style patch over JSON-domain authored source. Arrays are addressed only by canonical
|
|
30
|
+
* index (append is the JSON Pointer `/items/-` only). `test` and no-op detection compare numbers by
|
|
31
|
+
* SameValueZero (`0` equals `-0`), and explicit `add`/`replace` operands write `-0` as `+0`.
|
|
32
|
+
*/
|
|
28
33
|
type SourcePatch = readonly SourcePatchOperation[];
|
|
29
|
-
|
|
34
|
+
/**
|
|
35
|
+
* Operation failure codes. `invalid-array-index` covers any non-canonical-index segment on an Array
|
|
36
|
+
* parent (`'length'`, `'foo'`, `'01'`, structured `'-'`) in both path forms. `json-incompatible-value`
|
|
37
|
+
* is an `add`/`replace`/`test` operand outside Core's JSON domain; `source-access-failed` concerns
|
|
38
|
+
* unsafe access to source material only.
|
|
39
|
+
*/
|
|
40
|
+
type SourcePatchOperationFailureCode = 'invalid-path' | 'path-not-found' | 'path-not-traversable' | 'invalid-array-index' | 'invalid-move-target' | 'test-failed' | 'json-incompatible-value' | 'source-access-failed';
|
|
30
41
|
interface SourcePatchOperationFailure {
|
|
31
42
|
readonly code: SourcePatchOperationFailureCode;
|
|
32
43
|
readonly operationIndex: number;
|
package/dist/index.mjs
CHANGED
|
@@ -168,9 +168,19 @@ function inspectJsonValue(value) {
|
|
|
168
168
|
function isJsonValue(value) {
|
|
169
169
|
return inspectJsonValue(value).compatible;
|
|
170
170
|
}
|
|
171
|
-
/**
|
|
171
|
+
/**
|
|
172
|
+
* SameValueZero: `+0` equals `-0` and `NaN` equals `NaN`. Used only for SourcePatch comparisons
|
|
173
|
+
* (`test` and no-op detection); Runtime State has its own equality rule and does not use this.
|
|
174
|
+
*/
|
|
175
|
+
function sameValueZero(left, right) {
|
|
176
|
+
return left === right || typeof left === "number" && typeof right === "number" && Number.isNaN(left) && Number.isNaN(right);
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* JSON-domain equality used by the RFC6902 `test` operation; primitives compare by SameValueZero,
|
|
180
|
+
* so `-0` equals `0`. (SourcePatch no-op detection uses `structurallyEqual` in `source-patch.ts`.)
|
|
181
|
+
*/
|
|
172
182
|
function jsonEqual(left, right, seen = /* @__PURE__ */ new Set()) {
|
|
173
|
-
if (
|
|
183
|
+
if (sameValueZero(left, right)) return true;
|
|
174
184
|
if (typeof left !== "object" || left === null || typeof right !== "object" || right === null) return false;
|
|
175
185
|
if (!isJsonValue(left) || !isJsonValue(right)) return false;
|
|
176
186
|
if (seen.has(left) || seen.has(right)) return false;
|
|
@@ -204,6 +214,7 @@ const PATCH_ERROR_MESSAGES = {
|
|
|
204
214
|
"invalid-array-index": "The SourcePath contains an invalid Array index.",
|
|
205
215
|
"invalid-move-target": "The move destination is invalid relative to its source.",
|
|
206
216
|
"test-failed": "The test operation did not match the addressed value.",
|
|
217
|
+
"json-incompatible-value": "The SourcePatch operand is outside the JSON value domain.",
|
|
207
218
|
"source-access-failed": "The source could not be inspected safely."
|
|
208
219
|
};
|
|
209
220
|
function failure(code, message = PATCH_ERROR_MESSAGES[code]) {
|
|
@@ -288,12 +299,14 @@ function inspectStructuralContainer(value) {
|
|
|
288
299
|
function isCanonicalArrayIndex(key) {
|
|
289
300
|
return /^(?:0|[1-9]\d*)$/.test(key) && Number(key) < 4294967295;
|
|
290
301
|
}
|
|
291
|
-
|
|
302
|
+
/**
|
|
303
|
+
* Arrays have only index members: after path normalization, any segment that is not a canonical
|
|
304
|
+
* index fails `invalid-array-index` in both path forms. `null` means the JSON Pointer append
|
|
305
|
+
* position and is only returned when the caller allows it (callers pass `allowAppend` only for a
|
|
306
|
+
* final JSON Pointer `-` on an add-like operation).
|
|
307
|
+
*/
|
|
308
|
+
function getArrayIndex(segment, allowAppend = false) {
|
|
292
309
|
const key = String(segment);
|
|
293
|
-
if (!path.pointer && typeof segment === "string" && !isCanonicalArrayIndex(key)) return {
|
|
294
|
-
ok: true,
|
|
295
|
-
value: null
|
|
296
|
-
};
|
|
297
310
|
if (key === "-" && allowAppend) return {
|
|
298
311
|
ok: true,
|
|
299
312
|
value: null
|
|
@@ -345,7 +358,7 @@ function readAt(source, path) {
|
|
|
345
358
|
if (!container.ok) return container;
|
|
346
359
|
if (container.value === "opaque") return failure("path-not-traversable");
|
|
347
360
|
if (container.value === "array") {
|
|
348
|
-
const indexResult = getArrayIndex(
|
|
361
|
+
const indexResult = getArrayIndex(segment);
|
|
349
362
|
if (!indexResult.ok) return indexResult;
|
|
350
363
|
const length = readArrayLength(current);
|
|
351
364
|
if (!length.ok) return length;
|
|
@@ -419,17 +432,12 @@ function rebuildObject(container, segment, action, value, pointer = true, allowA
|
|
|
419
432
|
const key = String(segment);
|
|
420
433
|
const append = isArray && pointer && segment === "-" && allowArrayAppend;
|
|
421
434
|
const effectiveKey = append ? String(arrayLength.value) : key;
|
|
422
|
-
const arrayIndexResult = isArray ? getArrayIndex({
|
|
423
|
-
segments: [],
|
|
424
|
-
append: false,
|
|
425
|
-
pointer
|
|
426
|
-
}, segment, allowArrayAppend) : {
|
|
435
|
+
const arrayIndexResult = isArray ? getArrayIndex(segment, append) : {
|
|
427
436
|
ok: true,
|
|
428
437
|
value: null
|
|
429
438
|
};
|
|
430
439
|
if (!arrayIndexResult.ok) return arrayIndexResult;
|
|
431
440
|
const arrayIndex = append ? arrayLength.value : arrayIndexResult.value;
|
|
432
|
-
if (isArray && pointer && segment === "-" && !allowArrayAppend) return failure("invalid-array-index");
|
|
433
441
|
if (isArray && arrayIndex !== null) {
|
|
434
442
|
if (action === "add" && arrayIndex > arrayLength.value) return failure("invalid-array-index");
|
|
435
443
|
if (action !== "add" && arrayIndex >= arrayLength.value) return failure("invalid-array-index");
|
|
@@ -475,7 +483,7 @@ function modifyAt(source, path, modify) {
|
|
|
475
483
|
const key = String(segment);
|
|
476
484
|
if (index === path.segments.length - 1) return modify(container, segment);
|
|
477
485
|
if (containerKind.value === "array") {
|
|
478
|
-
const indexResult = getArrayIndex(
|
|
486
|
+
const indexResult = getArrayIndex(segment);
|
|
479
487
|
if (!indexResult.ok) return indexResult;
|
|
480
488
|
const length = readArrayLength(container);
|
|
481
489
|
if (!length.ok) return length;
|
|
@@ -495,10 +503,15 @@ function modifyRoot(source, value) {
|
|
|
495
503
|
value
|
|
496
504
|
};
|
|
497
505
|
}
|
|
498
|
-
|
|
506
|
+
/**
|
|
507
|
+
* Structurally copies `value`. With `canonicalizeNegativeZero` (explicit `add`/`replace` operands),
|
|
508
|
+
* every `-0` at any depth is written as `+0`; `copy`/`move` relocate existing material unchanged.
|
|
509
|
+
*/
|
|
510
|
+
function copyValue(value, canonicalizeNegativeZero = false) {
|
|
511
|
+
const canonical = (primitive) => canonicalizeNegativeZero && Object.is(primitive, -0) ? 0 : primitive;
|
|
499
512
|
if (value === null || typeof value !== "object") return {
|
|
500
513
|
ok: true,
|
|
501
|
-
value
|
|
514
|
+
value: canonical(value)
|
|
502
515
|
};
|
|
503
516
|
const containerKind = inspectStructuralContainer(value);
|
|
504
517
|
if (!containerKind.ok) return containerKind;
|
|
@@ -526,7 +539,7 @@ function copyValue(value) {
|
|
|
526
539
|
const child = descriptor.value;
|
|
527
540
|
let copied = {
|
|
528
541
|
ok: true,
|
|
529
|
-
value: child
|
|
542
|
+
value: canonical(child)
|
|
530
543
|
};
|
|
531
544
|
if (child !== null && typeof child === "object") {
|
|
532
545
|
const childKind = inspectStructuralContainer(child);
|
|
@@ -547,7 +560,7 @@ function copyValue(value) {
|
|
|
547
560
|
function structurallyEqual(left, right) {
|
|
548
561
|
const matched = /* @__PURE__ */ new WeakMap();
|
|
549
562
|
function equal(currentLeft, currentRight) {
|
|
550
|
-
if (
|
|
563
|
+
if (sameValueZero(currentLeft, currentRight)) return true;
|
|
551
564
|
if (typeof currentLeft !== "object" || currentLeft === null || typeof currentRight !== "object" || currentRight === null) return false;
|
|
552
565
|
const leftKind = inspectStructuralContainer(currentLeft);
|
|
553
566
|
const rightKind = inspectStructuralContainer(currentRight);
|
|
@@ -628,11 +641,11 @@ function applySourcePatch(source, patch) {
|
|
|
628
641
|
if (!isJsonValue(value)) return {
|
|
629
642
|
ok: false,
|
|
630
643
|
failure: operationError(operationIndex, {
|
|
631
|
-
code: "
|
|
632
|
-
message: "
|
|
644
|
+
code: "json-incompatible-value",
|
|
645
|
+
message: PATCH_ERROR_MESSAGES["json-incompatible-value"]
|
|
633
646
|
})
|
|
634
647
|
};
|
|
635
|
-
const copied = copyValue(value);
|
|
648
|
+
const copied = copyValue(value, true);
|
|
636
649
|
if (!copied.ok) return {
|
|
637
650
|
ok: false,
|
|
638
651
|
failure: operationError(operationIndex, copied.error)
|
|
@@ -656,8 +669,8 @@ function applySourcePatch(source, patch) {
|
|
|
656
669
|
if (!isJsonValue(value)) return {
|
|
657
670
|
ok: false,
|
|
658
671
|
failure: operationError(operationIndex, {
|
|
659
|
-
code: "
|
|
660
|
-
message: "
|
|
672
|
+
code: "json-incompatible-value",
|
|
673
|
+
message: PATCH_ERROR_MESSAGES["json-incompatible-value"]
|
|
661
674
|
})
|
|
662
675
|
};
|
|
663
676
|
const actual = readAt(working, path);
|
package/package.json
CHANGED