@joymerrevent/porters-connect 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-06
+
+**User マスタが PORTERS の全 17 項目を返すようになった版**です。破壊的変更はありませんが、
+`field` を省略したときの既定の挙動が変わります（下記 Changed）。
+
+### Added
+
+- **User マスタが reference の全 17 項目を返すようになりました**（[ADR-0060][adr60] D2）。
+  これまでカタログは 4 項目（`P_Id` / `P_Type` / `P_Name` / `P_Mail`）だけで、部署・電話・利用開始日・
+  登録者といった項目は**型にも存在せず、読む手段がありませんでした**。追加された 13 項目はこちらです。
+
+  `P_Department`（`System[Department]` — 入れ子で `P_Id` / `P_Name`）／ `P_Telephone` ／ `P_Mobile` ／
+  `P_MobileMail` ／ `P_UserName` ／ `P_TimeZone` ／ `P_Language` ／ `P_StartDate` ／ `P_EndDate` ／
+  `P_RegistrationDate` ／ `P_RegisteredBy` ／ `P_UpdateDate` ／ `P_UpdatedBy`
+
+  ```ts
+  const page = await t.user.search();
+  page.items[0]?.P_Department; // { P_Id: number | null; P_Name: string | null } | null
+  page.items[0]?.P_StartDate; // ISO 8601（"2026-04-01"）
+  ```
+
+### Changed
+
+- **`field` を省略した User Read が、カタログの全項目を要求するようになりました**（他のリソースと
+  同じ既定の扱い）。PORTERS は `field` 省略時に 4 項目しか返さないため、そのままでは
+  **型が約束する 13 項目が黙って `null` になる**からです。
+
+  4 項目だけで十分な場合は、`field` に必要なものだけを並べてください。
+  `field: []` は従来どおり「PORTERS 既定の 4 項目に委ねる」意味です。
+
+## [0.12.1] - 2026-09-03
+
+**フェイルセーフの修正 2 件**です。どちらも「黙って壊れる／安全側に倒しすぎている」場面を直したもので、
+**公開 API・型に変更はありません**（既存コードはそのまま動きます）。
+
+### Fixed
+
+- **`searchAll` が「渡したクエリの全件」を必ず返すようになりました**（[RV-32][rv32]）。
+  これまではクエリ オブジェクトへの参照を保持してページごとに読み直していたため、`for await` の反復中に
+  呼び出し側がそのオブジェクトを書き換えると、**同じ 1 回の `searchAll` の途中で検索条件が変わって**いました
+  （例外も警告も出ないまま「全件取ったつもりが途中から別条件の全件」になる）。
+
+  クエリは**最初のページを取る直前に 1 度だけ直列化**し、以降は `count` / `start` だけを差し替えます。
+  入れ子（`q.condition.P_Name.part` など）の書き換えも後続ページに影響しません。クエリ ガード
+  （`keywords` の長さ・`itemstate` の condition 制限など）の失敗が届くタイミングは従来どおりです。
+  対象は全データ系リソースと `field` / `partition` / `user`。
+
+- **適用されていないと分かっている失敗では、`create` / `createMany` が自動リトライされるようになりました**
+  （[ADR-0063][adr63] / [RV-22][rv22]）。非冪等な書き込みを不確定な失敗で再送しない方針（二重登録を作らない）は
+  変わりません。変えたのは「不確定」の判定で、これまでは `PortersNetworkError` かどうかだけを見ていたため、
+  **リクエストが一度も出ていない失敗**まで「適用されたかもしれない」扱いになっていました。
+
+  - **トークン取得に失敗した場合** — 送信前なので再送しても二重登録は起きません。
+  - **HTTP 429** — 処理される前に拒否された応答なので、同じく対象になります
+    （実 PORTERS はレート超過で切断する想定なので、効くのはプロキシ経由の環境です）。
+
+  **送信後の timeout / 切断 / 5xx では、従来どおり再送しません**（適用されたかどうか分からないため）。
+
 ## [0.12.0] - 2026-08-31
 
 **PORTERS の全リソースに対応した版**です。データ系は 6/13 から **13/13** になり、
@@ -511,11 +569,16 @@
 [adr59]: docs/adr/0059-read-field-bare-alias.md
 [adr60]: docs/adr/0060-full-resource-coverage-direction.md
 [adr61]: docs/adr/0061-phase-resource-surface.md
+[adr63]: docs/adr/0063-idempotency-guard-scope.md
+[rv22]: docs/reviews/rv/0022-ratelimit-create-no-retry.md
+[rv32]: docs/reviews/rv/0032-searchall-query-mutation.md
 [write-constraints]: docs/guide/write-constraints.md
 [lv]: docs/live-verification.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.12.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.12.1...HEAD
+[0.13.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.12.1...v0.13.0
+[0.12.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.9.0...v0.10.0

package/dist/index.d.ts

@@ -2041,6 +2041,19 @@ declare const FIELDS$2: {
     readonly P_Type: "Number";
     readonly P_Name: "SinglelineText";
     readonly P_Mail: "Mail";
+    readonly P_Department: "System[Department]";
+    readonly P_Telephone: "Telephone";
+    readonly P_Mobile: "Telephone";
+    readonly P_MobileMail: "Mail";
+    readonly P_UserName: "SinglelineText";
+    readonly P_TimeZone: "SinglelineText";
+    readonly P_Language: "SinglelineText";
+    readonly P_StartDate: "Date";
+    readonly P_EndDate: "Date";
+    readonly P_RegistrationDate: "System[DateTime]";
+    readonly P_RegisteredBy: "User";
+    readonly P_UpdateDate: "System[DateTime]";
+    readonly P_UpdatedBy: "User";
 };
 /** A decoded User (PORTERS operator). `P_Type`: 0 = standard user, 1 = system admin. */
 type User = ReadRecord<typeof FIELDS$2>;
@@ -2053,7 +2066,9 @@ type UserSearchQuery = {
     userType?: -1 | 0 | 1;
     /**
      * Output fields as **bare aliases** (`P_Name`); the library adds the `User.` prefix (ADR-0059).
-     * Omit to get the 4 core fields (this catalog).
+     * **Omit** to fetch every catalogued field (ADR-0020); narrow it when the extra HR fields
+     * (department / telephone / dates) are not interesting. Pass `[]` for PORTERS' own default —
+     * the 4 core fields it returns for a fieldless read.
      */
     field?: ReadFieldAlias<typeof FIELDS$2>[];
     count?: number;

package/dist/index.js

@@ -324,11 +324,13 @@ var createRequester = (o) => {
     let attempt = 0;
     for (; ; ) {
       await o.throttle.take(write);
+      let sent = false;
       try {
         const token = await o.auth.getAccessToken(
           forceRefresh ? { forceRefresh: true } : void 0
         );
         forceRefresh = false;
+        sent = true;
         const res = await o.transport.send(withAuth(req, token, write));
         return readResponse(res, parse);
       } catch (e) {
@@ -338,7 +340,9 @@ var createRequester = (o) => {
           forceRefresh = true;
           continue;
         }
-        if (e instanceof PortersNetworkError && write && !idempotent) throw e;
+        const mayHaveApplied = sent && e.category !== "rateLimit";
+        if (mayHaveApplied && e instanceof PortersNetworkError && write && !idempotent)
+          throw e;
         if (e.retryable && attempt < maxRetries) {
           attempt += 1;
           await sleep2(o.backoff(attempt - 1));
@@ -915,6 +919,11 @@ var appendPaging = (p, count, start) => {
   }
   if (start !== void 0) p.set("start", String(start));
 };
+var readUrlOf = (accessPoint, path, base, count, start) => {
+  const p = new URLSearchParams(base);
+  appendPaging(p, count, start);
+  return apiUrl(accessPoint, path, p);
+};
 var paginate = async function* (fetchPage) {
   let start = 0;
   for (; ; ) {
@@ -924,6 +933,9 @@ var paginate = async function* (fetchPage) {
     if (page.items.length === 0 || start >= page.total) return;
   }
 };
+var paginateOnce = async function* (prepare) {
+  yield* paginate(prepare());
+};
 
 // src/resources/query.ts
 var KEYWORDS_MAX_CHARS = 100;
@@ -1144,7 +1156,7 @@ var firstWriteResultId = (body, path, name) => {
   }
   return first.id;
 };
-var buildReadUrl = (accessPoint, partition, path, q, ctx) => {
+var buildReadParams = (partition, q, ctx) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
   for (const [key, value] of Object.entries(ctx.params ?? {}))
@@ -1159,8 +1171,7 @@ var buildReadUrl = (accessPoint, partition, path, q, ctx) => {
     p.set("field", entries.join(","));
   }
   appendReadQuery(p, q, ctx);
-  appendPaging(p, q.count, q.start);
-  return apiUrl(accessPoint, path, p);
+  return p;
 };
 var buildWriteUrl = (accessPoint, partition, path) => apiUrl(
   accessPoint,
@@ -1175,12 +1186,13 @@ var createResource = (config, deps) => {
   const idAlias = config.idAlias ?? "P_Id";
   const decode = decoderFor(config.fields);
   const defaultFields = Object.keys(config.fields);
-  const readUrl = (q) => buildReadUrl(deps.accessPoint, deps.partition, config.path, q, {
+  const readParams = (q) => buildReadParams(deps.partition, q, {
     prefix: config.prefix,
     fields: fieldMap,
     references,
     params: config.readParams
   });
+  const readUrl = (q) => readUrlOf(deps.accessPoint, config.path, readParams(q), q.count, q.start);
   const writeUrl = () => buildWriteUrl(deps.accessPoint, deps.partition, config.path);
   const firstWriteId = (body) => firstWriteResultId(body, config.path, config.name);
   const decoderWith = (expand) => {
@@ -1193,7 +1205,19 @@ var createResource = (config, deps) => {
     readUrl({ ...query, field: query.field ?? defaultFields }),
     decoderWith(query.expand)
   );
-  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  const searchAll = (query = {}) => paginateOnce(() => {
+    const base = readParams({
+      ...query,
+      field: query.field ?? defaultFields
+    });
+    const decode2 = decoderWith(query.expand);
+    return (count, start) => runRead(
+      deps.requester,
+      config.name,
+      readUrlOf(deps.accessPoint, config.path, base, count, start),
+      decode2
+    );
+  });
   const get = async (id, options = {}) => {
     const condition = { [idAlias]: { eq: id } };
     const page = await search({
@@ -2012,21 +2036,24 @@ var PARTITION_DESCRIPTOR = {
   prefix: "Partition",
   fields: FIELDS13
 };
-var buildUrl = (accessPoint, q) => {
+var buildParams = (q) => {
   const p = new URLSearchParams();
   p.set("request_type", String(q.requestType ?? 1));
-  appendPaging(p, q.count, q.start);
-  return apiUrl(accessPoint, "partition", p);
+  return p;
 };
 var createPartitionResource = (deps) => {
   const decode = decoderFor(FIELDS13);
-  const search = async (query = {}) => runRead(
-    deps.requester,
-    PARTITION_DESCRIPTOR.name,
-    buildUrl(deps.accessPoint, query),
-    decode
-  );
-  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  const readUrl = (q) => readUrlOf(deps.accessPoint, "partition", buildParams(q), q.count, q.start);
+  const search = async (query = {}) => runRead(deps.requester, PARTITION_DESCRIPTOR.name, readUrl(query), decode);
+  const searchAll = (query = {}) => paginateOnce(() => {
+    const base = buildParams(query);
+    return (count, start) => runRead(
+      deps.requester,
+      PARTITION_DESCRIPTOR.name,
+      readUrlOf(deps.accessPoint, "partition", base, count, start),
+      decode
+    );
+  });
   return { search, searchAll };
 };
 
@@ -2035,7 +2062,24 @@ var FIELDS14 = {
   P_Id: "System[Id]",
   P_Type: "Number",
   P_Name: "SinglelineText",
-  P_Mail: "Mail"
+  P_Mail: "Mail",
+  // 部署は User と同じ入れ子で返る（`<Department><Department.P_Id>…` — ADR-0061 案3a）。
+  P_Department: "System[Department]",
+  P_Telephone: "Telephone",
+  P_Mobile: "Telephone",
+  P_MobileMail: "Mail",
+  P_UserName: "SinglelineText",
+  // タイムゾーン名（`Asia/Tokyo` 等）。PORTERS は Timezone List の名前をそのまま返す。
+  P_TimeZone: "SinglelineText",
+  P_Language: "SinglelineText",
+  P_StartDate: "Date",
+  P_EndDate: "Date",
+  P_RegistrationDate: "System[DateTime]",
+  // 登録者・更新者は `User` 型＝汎用の組み立てが `(User.P_Id,…)` を付けて要求する。
+  // VERIFY(live): User Read で User 型の項目を `()` 付きで要求できるかは未確認（LV-17 と同型）。
+  P_RegisteredBy: "User",
+  P_UpdateDate: "System[DateTime]",
+  P_UpdatedBy: "User"
 };
 var USER_DESCRIPTOR = {
   name: "User",
@@ -2044,29 +2088,40 @@ var USER_DESCRIPTOR = {
   fields: FIELDS14
 };
 var FIELD_MAP = new Map(Object.entries(FIELDS14));
-var buildUrl2 = (accessPoint, partition, q) => {
+var DEFAULT_FIELDS2 = Object.keys(FIELDS14);
+var buildParams2 = (partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
   p.set("request_type", String(q.requestType ?? 1));
   p.set("user_type", String(q.userType ?? -1));
-  if (q.field && q.field.length > 0) {
+  const field = q.field ?? DEFAULT_FIELDS2;
+  if (field.length > 0) {
     p.set(
       "field",
-      qualifyReadFields(USER_DESCRIPTOR.prefix, FIELD_MAP, q.field).join(",")
+      qualifyReadFields(USER_DESCRIPTOR.prefix, FIELD_MAP, field).join(",")
     );
   }
-  appendPaging(p, q.count, q.start);
-  return apiUrl(accessPoint, "user", p);
+  return p;
 };
 var createUserResource = (deps) => {
   const decode = decoderFor(FIELDS14);
-  const search = async (query = {}) => runRead(
-    deps.requester,
-    USER_DESCRIPTOR.name,
-    buildUrl2(deps.accessPoint, deps.partition, query),
-    decode
+  const readUrl = (q) => readUrlOf(
+    deps.accessPoint,
+    "user",
+    buildParams2(deps.partition, q),
+    q.count,
+    q.start
   );
-  const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
+  const search = async (query = {}) => runRead(deps.requester, USER_DESCRIPTOR.name, readUrl(query), decode);
+  const searchAll = (query = {}) => paginateOnce(() => {
+    const base = buildParams2(deps.partition, query);
+    return (count, start) => runRead(
+      deps.requester,
+      USER_DESCRIPTOR.name,
+      readUrlOf(deps.accessPoint, "user", base, count, start),
+      decode
+    );
+  });
   const current = async () => (await search({ requestType: 0, count: 1 })).items[0];
   return { search, searchAll, current };
 };
@@ -2105,23 +2160,32 @@ var FIELD_DESCRIPTOR = {
   prefix: "Field",
   fields: FIELDS15
 };
-var buildUrl3 = (accessPoint, partition, q) => {
+var buildParams3 = (partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
   p.set("resource", String(RESOURCE_VALUE[q.resource]));
   p.set("active", String(q.active ?? -1));
-  appendPaging(p, q.count, q.start);
-  return apiUrl(accessPoint, "field", p);
+  return p;
 };
 var createFieldResource = (deps) => {
   const decode = decoderFor(FIELDS15);
-  const search = async (query) => runRead(
-    deps.requester,
-    FIELD_DESCRIPTOR.name,
-    buildUrl3(deps.accessPoint, deps.partition, query),
-    decode
+  const readUrl = (q) => readUrlOf(
+    deps.accessPoint,
+    "field",
+    buildParams3(deps.partition, q),
+    q.count,
+    q.start
   );
-  const searchAll = (query) => paginate((count, start) => search({ ...query, count, start }));
+  const search = async (query) => runRead(deps.requester, FIELD_DESCRIPTOR.name, readUrl(query), decode);
+  const searchAll = (query) => paginateOnce(() => {
+    const base = buildParams3(deps.partition, query);
+    return (count, start) => runRead(
+      deps.requester,
+      FIELD_DESCRIPTOR.name,
+      readUrlOf(deps.accessPoint, "field", base, count, start),
+      decode
+    );
+  });
   return { search, searchAll };
 };
 
@@ -2140,7 +2204,7 @@ var OPTION_DESCRIPTOR = {
   prefix: "Option",
   fields: FIELDS16
 };
-var buildUrl4 = (accessPoint, partition, q) => {
+var buildUrl = (accessPoint, partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
   if (q.alias !== void 0) p.set("alias", q.alias);
@@ -2164,7 +2228,7 @@ var createOptionResource = (deps) => {
   const search = async (query = {}) => deps.requester.request(
     {
       method: "GET",
-      url: buildUrl4(deps.accessPoint, deps.partition, query),
+      url: buildUrl(deps.accessPoint, deps.partition, query),
       headers: {}
     },
     (body) => {