@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 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`, or
277
- `source-access-failed`, and `operationIndex` is the failing operation's
278
- position in the patch. A failed patch leaves the committed source and revision
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
- type SourcePatchOperationFailureCode = 'invalid-path' | 'path-not-found' | 'path-not-traversable' | 'invalid-array-index' | 'invalid-move-target' | 'test-failed' | 'source-access-failed';
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
- /** JSON-domain equality used by the RFC6902 `test` operation. (SourcePatch no-op detection uses `structurallyEqual` in `source-patch.ts`.) */
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 (Object.is(left, right)) return true;
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
- function getArrayIndex(path, segment, allowAppend = false) {
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(path, segment);
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(path, segment);
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
- function copyValue(value) {
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 (Object.is(currentLeft, currentRight)) return true;
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: "source-access-failed",
632
- message: "SourcePatch operands must be JsonValue."
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: "source-access-failed",
660
- message: "SourcePatch operands must be JsonValue."
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
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.0.3",
7
+ "version": "0.0.4",
8
8
  "author": "DevilTea <ch19980814@gmail.com>",
9
9
  "license": "MIT",
10
10
  "homepage": "https://github.com/DevilTea/widget/tree/main/packages/core#readme",