@uzuhq/code-sdk 0.3.8

package/dist/dev-state-patch.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @docs
+ * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ *
+ * `__uzu_dev.mergeRawState` / `__uzu_dev.patchRawState` の中身。
+ * scenario state を「object 階層の部分更新 (RFC 7396)」と「array 要素単体の書換
+ * 含む path-based ops (RFC 6902)」で書き換えるための utility。
+ */
+/**
+ * RFC 7396 風 Merge Patch。
+ *
+ * RFC 7396 strict との差分:
+ * - `null` は target 側の **削除ではなく** null をセットする (`timerEndsAt: null`
+ *   のような nullable field を狙い撃ちするユースケースを優先)
+ * - 値を削除したいときは {@link JsonPatchOp} の `remove` を使う
+ *
+ * Generic は使い手側の type を残すための shape ヒントで、ランタイム上は
+ * `Record<string, unknown>` と等価。
+ */
+export type JsonMergePatch<S = unknown> = Partial<{
+    [K in keyof S]: S[K] extends unknown[] ? S[K] : S[K] extends object ? JsonMergePatch<S[K]> : S[K] | null;
+}> & Record<string, unknown>;
+/**
+ * RFC 6902 JSON Patch operation。
+ *
+ * - `add` / `replace` / `test`: `value` 必須
+ * - `remove`: `value` / `from` 不要
+ * - `move` / `copy`: `from` 必須 (JSON Pointer)
+ * - `path` は JSON Pointer (例: `/board/1/4`、root は空文字)
+ */
+export type JsonPatchOp = {
+    op: 'add';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+} | {
+    op: 'replace';
+    path: string;
+    value: unknown;
+} | {
+    op: 'move';
+    path: string;
+    from: string;
+} | {
+    op: 'copy';
+    path: string;
+    from: string;
+} | {
+    op: 'test';
+    path: string;
+    value: unknown;
+};
+/**
+ * RFC 7396 (Merge Patch) を target に in-place 適用する。
+ *
+ * 規則:
+ * - `undefined` は no-op (key 自体を patch から落としたのと同じ)
+ * - `null` は **null をセット** (RFC 7396 strict と異なる、deletion はしない)
+ * - patch が object かつ target も object → 再帰 merge
+ * - patch が array → atomic replace (要素単位 merge なし、RFC 7396 spec 通り)
+ * - patch が primitive → overwrite
+ * - **target が array で patch が non-array object** → throw (silent な
+ *   `[..., ...]` → `{ "0": ..., "1": ... }` 化を防ぐ)
+ *
+ * 型 mismatch (例: object → primitive) は overwrite で許可する。
+ */
+export declare function applyJsonMergePatch(target: Record<string, unknown>, patch: JsonMergePatch): void;
+/**
+ * RFC 6902 (JSON Patch) operations を target に in-place 適用する。
+ *
+ * 1 op でも失敗したら **その時点で throw** する (RFC 6902 spec: operations は
+ * sequentially evaluate、失敗時の rollback は規定なし)。caller が atomic に
+ * したいなら state を事前に snapshot しておく。
+ *
+ * root pointer (`''`) は本実装では `add` / `replace` のみ許可し、
+ * doc のフィールドを丸ごと差し替える形で動く (= 結局 `setRawState` で十分な
+ * ケースなので、わざわざ `patchRawState` で使うことはほぼない)。
+ */
+export declare function applyJsonPatch(target: Record<string, unknown>, ops: JsonPatchOp[]): void;

package/dist/dev-state-patch.js

@@ -0,0 +1,295 @@
+/**
+ * @docs
+ * - 外部 automation API: docs/docs/play_screen_v3/sdk-guide/dev-hooks.md
+ *
+ * `__uzu_dev.mergeRawState` / `__uzu_dev.patchRawState` の中身。
+ * scenario state を「object 階層の部分更新 (RFC 7396)」と「array 要素単体の書換
+ * 含む path-based ops (RFC 6902)」で書き換えるための utility。
+ */
+// ─── RFC 7396 Merge Patch ────────────────────────────────────────────
+/**
+ * RFC 7396 (Merge Patch) を target に in-place 適用する。
+ *
+ * 規則:
+ * - `undefined` は no-op (key 自体を patch から落としたのと同じ)
+ * - `null` は **null をセット** (RFC 7396 strict と異なる、deletion はしない)
+ * - patch が object かつ target も object → 再帰 merge
+ * - patch が array → atomic replace (要素単位 merge なし、RFC 7396 spec 通り)
+ * - patch が primitive → overwrite
+ * - **target が array で patch が non-array object** → throw (silent な
+ *   `[..., ...]` → `{ "0": ..., "1": ... }` 化を防ぐ)
+ *
+ * 型 mismatch (例: object → primitive) は overwrite で許可する。
+ */
+export function applyJsonMergePatch(target, patch) {
+    if (Array.isArray(target)) {
+        // 入口でガード済みのはずだが、再帰内で array 階層に踏み込むこともあるので
+        // defense in depth で再度ガード。
+        throw new TypeError('[uzu_dev] mergeRawState: cannot deep-merge into an array field. ' +
+            'Use patchRawState ({ op: "replace", path: "/.../<index>" }) for element-level writes, ' +
+            'or pass a full array to atomic-replace it.');
+    }
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            target[key] = null;
+            continue;
+        }
+        const current = target[key];
+        if (typeof value === 'object' &&
+            !Array.isArray(value) &&
+            current !== null &&
+            typeof current === 'object') {
+            if (Array.isArray(current)) {
+                // 既存値が array なのに patch 側は plain object → 明示的に止める
+                // (silent に array が dict 化する破壊を防ぐ)。
+                throw new TypeError(`[uzu_dev] mergeRawState: refusing to merge a plain object into array field "${key}". ` +
+                    `Use patchRawState ({ op: "replace", path: "/${key}/<index>" }) for element-level writes, ` +
+                    `or pass a full array to atomic-replace it.`);
+            }
+            applyJsonMergePatch(current, value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+}
+// ─── RFC 6902 JSON Patch ─────────────────────────────────────────────
+/**
+ * JSON Pointer (RFC 6901) を tokens に分解する。
+ * `/board/1/~04` → `['board', '1', '~4']`
+ *
+ * RFC 6901 のエスケープ:
+ * - `~1` → `/`
+ * - `~0` → `~`
+ *
+ * 復号順は ~1 → ~0。逆順で解くと `~01` が `/` に化けるので注意。
+ */
+function parseJsonPointer(pointer) {
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/')) {
+        throw new TypeError(`[uzu_dev] invalid JSON Pointer: ${pointer} (must start with "/")`);
+    }
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((token) => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+/**
+ * JSON Pointer の **親 container** と **末端 key** に解決する。
+ * root pointer (`''`) は対応外: 呼び出し側で別途扱う。
+ */
+function resolveParent(doc, tokens) {
+    if (tokens.length === 0) {
+        throw new TypeError('[uzu_dev] root pointer ("") is not addressable by this helper');
+    }
+    let current = doc;
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const token = tokens[i];
+        if (current === null || typeof current !== 'object') {
+            throw new TypeError(`[uzu_dev] JSON Pointer path "${tokens.slice(0, i + 1).join('/')}" goes through a non-container`);
+        }
+        if (Array.isArray(current)) {
+            const idx = parseArrayIndex(token, current.length, /* allowAppend */ false);
+            current = current[idx];
+        }
+        else {
+            current = current[token];
+        }
+    }
+    if (current === null || typeof current !== 'object') {
+        throw new TypeError(`[uzu_dev] JSON Pointer parent "${tokens.slice(0, -1).join('/')}" is not a container`);
+    }
+    return {
+        parent: current,
+        key: tokens[tokens.length - 1],
+    };
+}
+/**
+ * JSON Pointer から値を取得する。root pointer は doc 自体。
+ * 存在しない path は throw する。
+ */
+function getByPointer(doc, pointer) {
+    const tokens = parseJsonPointer(pointer);
+    let current = doc;
+    for (const token of tokens) {
+        if (current === null || typeof current !== 'object') {
+            throw new TypeError(`[uzu_dev] JSON Pointer path "${pointer}" goes through a non-container`);
+        }
+        if (Array.isArray(current)) {
+            const idx = parseArrayIndex(token, current.length, /* allowAppend */ false);
+            current = current[idx];
+        }
+        else {
+            const obj = current;
+            if (!(token in obj)) {
+                throw new TypeError(`[uzu_dev] JSON Pointer path "${pointer}" does not exist`);
+            }
+            current = obj[token];
+        }
+    }
+    return current;
+}
+/**
+ * Array index token を numeric index に解決する。
+ * `'-'` は append (RFC 6902 仕様、`add` 操作のみ許可) で `length` を返す。
+ */
+function parseArrayIndex(token, length, allowAppend) {
+    if (token === '-') {
+        if (!allowAppend) {
+            throw new TypeError('[uzu_dev] array append ("-") is only valid for `add` operations');
+        }
+        return length;
+    }
+    // RFC 6901: array index は ASCII 数字のみ。先頭 0 は禁止 (ただし "0" 単独は OK)。
+    if (!/^(?:0|[1-9][0-9]*)$/.test(token)) {
+        throw new TypeError(`[uzu_dev] invalid array index "${token}"`);
+    }
+    const idx = Number(token);
+    if (idx < 0 || idx > length) {
+        throw new RangeError(`[uzu_dev] array index ${idx} out of range (length=${length})`);
+    }
+    return idx;
+}
+/**
+ * 値の深い等価判定 (RFC 6902 `test` 用)。`JSON.stringify` ベース。
+ * `undefined` を含む値や key 順序差まで真面目に見るほどには使わないので十分。
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * RFC 6902 (JSON Patch) operations を target に in-place 適用する。
+ *
+ * 1 op でも失敗したら **その時点で throw** する (RFC 6902 spec: operations は
+ * sequentially evaluate、失敗時の rollback は規定なし)。caller が atomic に
+ * したいなら state を事前に snapshot しておく。
+ *
+ * root pointer (`''`) は本実装では `add` / `replace` のみ許可し、
+ * doc のフィールドを丸ごと差し替える形で動く (= 結局 `setRawState` で十分な
+ * ケースなので、わざわざ `patchRawState` で使うことはほぼない)。
+ */
+export function applyJsonPatch(target, ops) {
+    for (const op of ops) {
+        applyOne(target, op);
+    }
+}
+function applyOne(doc, op) {
+    switch (op.op) {
+        case 'add': {
+            const tokens = parseJsonPointer(op.path);
+            if (tokens.length === 0) {
+                // root への add は doc 全体の差し替え。doc は in-place mutate しか
+                // できないので、ここでは現実的に全 key を入れ替える形で実現する。
+                replaceRoot(doc, op.value);
+                return;
+            }
+            const { parent, key } = resolveParent(doc, tokens);
+            if (Array.isArray(parent)) {
+                const idx = parseArrayIndex(key, parent.length, /* allowAppend */ true);
+                parent.splice(idx, 0, op.value);
+            }
+            else {
+                parent[key] = op.value;
+            }
+            return;
+        }
+        case 'remove': {
+            const tokens = parseJsonPointer(op.path);
+            if (tokens.length === 0) {
+                throw new TypeError('[uzu_dev] cannot remove the root document');
+            }
+            const { parent, key } = resolveParent(doc, tokens);
+            if (Array.isArray(parent)) {
+                const idx = parseArrayIndex(key, parent.length - 1, /* allowAppend */ false);
+                parent.splice(idx, 1);
+            }
+            else {
+                if (!(key in parent)) {
+                    throw new TypeError(`[uzu_dev] cannot remove non-existent path "${op.path}"`);
+                }
+                delete parent[key];
+            }
+            return;
+        }
+        case 'replace': {
+            const tokens = parseJsonPointer(op.path);
+            if (tokens.length === 0) {
+                replaceRoot(doc, op.value);
+                return;
+            }
+            const { parent, key } = resolveParent(doc, tokens);
+            if (Array.isArray(parent)) {
+                const idx = parseArrayIndex(key, parent.length - 1, /* allowAppend */ false);
+                parent[idx] = op.value;
+            }
+            else {
+                if (!(key in parent)) {
+                    throw new TypeError(`[uzu_dev] cannot replace non-existent path "${op.path}"`);
+                }
+                parent[key] = op.value;
+            }
+            return;
+        }
+        case 'move': {
+            if (op.from === op.path)
+                return;
+            // RFC 6902: from が path の真の prefix だと不正 (循環移動)
+            if (isProperPrefixPointer(op.from, op.path)) {
+                throw new TypeError(`[uzu_dev] cannot move into own descendant: from="${op.from}" path="${op.path}"`);
+            }
+            const value = getByPointer(doc, op.from);
+            applyOne(doc, { op: 'remove', path: op.from });
+            applyOne(doc, { op: 'add', path: op.path, value });
+            return;
+        }
+        case 'copy': {
+            const value = getByPointer(doc, op.from);
+            // RFC 6902: copy は値を deep clone することを要求する。共有参照が後段の
+            // remove/replace で破壊されるのを防ぐため `structuredClone` を使う。
+            const cloned = structuredClone(value);
+            applyOne(doc, { op: 'add', path: op.path, value: cloned });
+            return;
+        }
+        case 'test': {
+            const value = getByPointer(doc, op.path);
+            if (!deepEqual(value, op.value)) {
+                throw new Error(`[uzu_dev] test failed at "${op.path}"`);
+            }
+            return;
+        }
+        default: {
+            const exhaustive = op;
+            throw new TypeError(`[uzu_dev] unknown JSON Patch op: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+function isProperPrefixPointer(prefix, path) {
+    if (prefix === '')
+        return path !== '';
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/**
+ * root pointer (`''`) への add / replace 用。doc を in-place で空にして
+ * value の中身を流し込む。value が object でない場合は Record の形に
+ * 入らないので throw する (root を primitive / array に置換はサポート対象外、
+ * setRawState を使うべき)。
+ */
+function replaceRoot(doc, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError('[uzu_dev] root replace requires a plain object value; use setRawState for full state replacement');
+    }
+    for (const key of Object.keys(doc))
+        delete doc[key];
+    Object.assign(doc, value);
+}

package/dist/dev-state-patch.test.d.ts

@@ -0,0 +1 @@
+export {};