@ai0x0/utils 0.7.1 → 0.7.2

package/es/backend/index.d.ts

@@ -2,4 +2,5 @@ export * from "./actions/index.js";
 export * from "./route-operation/index.js";
 export * from "./schemas/index.js";
 export * from "./errors.js";
+export * from "./response-headers.js";
 export * from "./scope.js";

package/es/backend/index.js

@@ -2,4 +2,5 @@ export * from "./actions/index.js";
 export * from "./route-operation/index.js";
 export * from "./schemas/index.js";
 export * from "./errors.js";
+export * from "./response-headers.js";
 export * from "./scope.js";

package/es/backend/response-headers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 记一个响应头，等这次请求出结果时一起发出去。
+ *
+ * @param owner 这次请求的会话对象 —— 处理器收到的那个 session（本库把 getSession 的返回值
+ *   原样传给处理器，所以业务那边手上的就是它）。传 undefined 等于不记。
+ */
+export declare function setResponseHeader(owner: unknown, name: string, value: string): void;
+/**
+ * 把这次请求攒下的头写进已经建好的那条响应。**工厂出口用**。
+ *
+ * 为什么是「建好之后再写」而不是建的时候一起传：TypedNextResponse.json 的第二个参数只收
+ * status（见 next-rest-framework 的类型），而响应对象本身的 headers 是可写的。
+ */
+export declare function withResponseHeaders<T extends {
+    headers: Headers;
+}>(response: T, owner: unknown): T;

package/es/backend/response-headers.js

@@ -0,0 +1,79 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+// =============================================================================
+// 给这次请求的响应挂一个额外的头
+// =============================================================================
+// 处理器深处发生了「顺带得告诉客户端」的事，而那一层够不着响应 —— 典型是扣费：扣完之后
+// 新余额只有那一层知道，界面上却要立刻更新；不给条路的话，客户端只能在每次请求之后再问一遍
+// 余额，或者干脆一直显示旧数。
+//
+// 通道是一张 WeakMap，键是**这次请求解析出来的会话对象**（getSession 每个请求回一个新的，
+// 见 sessionLoader）。两个「为什么不是」：
+//   · 不是 AsyncLocalStorage —— 那要求运行时开 node 兼容，而这套要能在边缘运行时里跑；
+//   · 不是 req —— 业务那一层常常只拿得到会话（扣费函数收的就是它），够不着请求对象。
+//
+// **取一次就没了**（takeResponseHeaders 会清掉）：一个请求攒的头不该漏进下一个 —— 键虽然
+// 每请求一个，但调用方完全可能把会话对象缓存起来复用。
+//
+// 键认不出、这次没人挂过头，一律当作没有。这是个可选的补丁，任何一步不对劲都不该影响那条
+// 响应本身。
+
+var pending = new WeakMap();
+
+/**
+ * 记一个响应头，等这次请求出结果时一起发出去。
+ *
+ * @param owner 这次请求的会话对象 —— 处理器收到的那个 session（本库把 getSession 的返回值
+ *   原样传给处理器，所以业务那边手上的就是它）。传 undefined 等于不记。
+ */
+export function setResponseHeader(owner, name, value) {
+  if (!isKey(owner)) {
+    return;
+  }
+  pending.set(owner, _objectSpread(_objectSpread({}, pending.get(owner)), {}, _defineProperty({}, name, value)));
+}
+
+// 会话对象长什么样由调用方定（TSession 是个不带约束的泛型），所以这两个口子收 unknown，
+// 在这儿把「能不能当 WeakMap 的键」判掉 —— 让每个调用点各写一遍类型断言是把脏活外包出去。
+function isKey(owner) {
+  return _typeof(owner) === "object" && owner !== null;
+}
+
+/** 取出并清空这次请求攒下的头。**工厂出口用**，业务不该调它。 */
+function takeResponseHeaders(owner) {
+  if (!isKey(owner)) {
+    return undefined;
+  }
+  var headers = pending.get(owner);
+  if (headers) {
+    pending.delete(owner);
+  }
+  return headers;
+}
+
+/**
+ * 把这次请求攒下的头写进已经建好的那条响应。**工厂出口用**。
+ *
+ * 为什么是「建好之后再写」而不是建的时候一起传：TypedNextResponse.json 的第二个参数只收
+ * status（见 next-rest-framework 的类型），而响应对象本身的 headers 是可写的。
+ */
+export function withResponseHeaders(response, owner) {
+  var extra = takeResponseHeaders(owner);
+  for (var _i = 0, _Object$entries = Object.entries(extra !== null && extra !== void 0 ? extra : {}); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      name = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    response.headers.set(name, value);
+  }
+  return response;
+}

package/es/backend/route-operation/read-operation-core.js

@@ -11,6 +11,7 @@ import { routeOperation, TypedNextResponse } from "next-rest-framework";
 import { listBodySchema } from "../schemas/index.js";
 import { createOpenApiOperation } from "./open-api-operation.js";
 import { callerIdOf, getDefaultTags, getReadParams, handleOperationError } from "./operation-common.js";
+import { withResponseHeaders } from "../response-headers.js";
 
 // ==============================================================================
 // GET single operation
@@ -106,9 +107,9 @@ export function createGetOperationFactory(_ref) {
               case 19:
                 result = _context.sent;
               case 20:
-                return _context.abrupt("return", TypedNextResponse.json(result, {
+                return _context.abrupt("return", withResponseHeaders(TypedNextResponse.json(result, {
                   status: 200
-                }));
+                }), session));
               case 23:
                 _context.prev = 23;
                 _context.t1 = _context["catch"](0);
@@ -223,9 +224,9 @@ export function createGetListOperationFactory(_ref5) {
               case 18:
                 result = _context2.sent;
               case 19:
-                return _context2.abrupt("return", TypedNextResponse.json(result, {
+                return _context2.abrupt("return", withResponseHeaders(TypedNextResponse.json(result, {
                   status: 200
-                }));
+                }), session));
               case 22:
                 _context2.prev = 22;
                 _context2.t1 = _context2["catch"](0);

package/es/backend/route-operation/write-operation-core.js

@@ -12,6 +12,7 @@ import { z } from "zod";
 import { createOpenApiOperation } from "./open-api-operation.js";
 import { callerIdOf, getDefaultTags, handleOperationError, readPostBody, resolveAccess, sessionLoader } from "./operation-common.js";
 import { NO_SCOPE } from "../scope.js";
+import { withResponseHeaders } from "../response-headers.js";
 
 // ==============================================================================
 // POST create operation
@@ -153,9 +154,9 @@ export function createPostOperationFactory(_ref) {
                 _context.t2 = raw;
               case 32:
                 data = _context.t2;
-                return _context.abrupt("return", TypedNextResponse.json(data, {
+                return _context.abrupt("return", withResponseHeaders(TypedNextResponse.json(data, {
                   status: 200
-                }));
+                }), session));
               case 36:
                 _context.prev = 36;
                 _context.t3 = _context["catch"](0);
@@ -213,7 +214,7 @@ export function createPutOperationFactory(_ref5) {
         status: 200
       }]).handler( /*#__PURE__*/function () {
         var _ref8 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee2(req) {
-          var _yield$loadSession, loadSession, _yield$resolveAccess2, scope, body, extraBody, editorId, params, raw, data;
+          var loadSession, _yield$resolveAccess2, scope, body, extraBody, session, editorId, params, raw, data;
           return _regeneratorRuntime().wrap(function _callee2$(_context2) {
             while (1) switch (_context2.prev = _context2.next) {
               case 0:
@@ -246,35 +247,17 @@ export function createPutOperationFactory(_ref5) {
                 _context2.next = 17;
                 return loadSession();
               case 17:
-                _context2.t2 = _yield$loadSession = _context2.sent;
-                _context2.t1 = _context2.t2 === null;
-                if (_context2.t1) {
-                  _context2.next = 21;
-                  break;
-                }
-                _context2.t1 = _yield$loadSession === void 0;
-              case 21:
-                if (!_context2.t1) {
-                  _context2.next = 25;
-                  break;
-                }
-                _context2.t3 = void 0;
-                _context2.next = 26;
-                break;
-              case 25:
-                _context2.t3 = _yield$loadSession.userId;
-              case 26:
-                editorId = _context2.t3;
-                // editorId 同样**最后**展开：它是审计字段，让请求体覆盖等于让人随便写「是谁改的」。
+                session = _context2.sent;
+                editorId = session === null || session === void 0 ? void 0 : session.userId; // editorId 同样**最后**展开：它是审计字段，让请求体覆盖等于让人随便写「是谁改的」。
                 // 理由与 POST 那边的归属戳一样，见那里的说明。
                 params = _objectSpread(_objectSpread(_objectSpread({}, body), extraBody), {}, {
                   editorId: editorId
                 });
                 if (!(table && db)) {
-                  _context2.next = 34;
+                  _context2.next = 26;
                   break;
                 }
-                _context2.next = 31;
+                _context2.next = 23;
                 return createAction({
                   bodySchema: schemas.body,
                   db: db,
@@ -282,19 +265,19 @@ export function createPutOperationFactory(_ref5) {
                 })(params, {
                   scope: scope
                 });
-              case 31:
-                _context2.t4 = _context2.sent;
-                _context2.next = 35;
+              case 23:
+                _context2.t1 = _context2.sent;
+                _context2.next = 27;
                 break;
-              case 34:
-                _context2.t4 = params;
-              case 35:
-                raw = _context2.t4;
+              case 26:
+                _context2.t1 = params;
+              case 27:
+                raw = _context2.t1;
                 if (!handler) {
-                  _context2.next = 42;
+                  _context2.next = 34;
                   break;
                 }
-                _context2.next = 39;
+                _context2.next = 31;
                 return handler({
                   data: raw,
                   // 同 POST：callerId 不进 createAction 那一份（它会被 .set() 原样写进 UPDATE，
@@ -304,26 +287,26 @@ export function createPutOperationFactory(_ref5) {
                   }),
                   req: req
                 });
-              case 39:
-                _context2.t5 = _context2.sent;
-                _context2.next = 43;
+              case 31:
+                _context2.t2 = _context2.sent;
+                _context2.next = 35;
                 break;
-              case 42:
-                _context2.t5 = raw;
-              case 43:
-                data = _context2.t5;
-                return _context2.abrupt("return", TypedNextResponse.json(data, {
+              case 34:
+                _context2.t2 = raw;
+              case 35:
+                data = _context2.t2;
+                return _context2.abrupt("return", withResponseHeaders(TypedNextResponse.json(data, {
                   status: 200
-                }));
-              case 47:
-                _context2.prev = 47;
-                _context2.t6 = _context2["catch"](0);
-                return _context2.abrupt("return", handleOperationError(_context2.t6, catchHandler));
-              case 50:
+                }), session));
+              case 39:
+                _context2.prev = 39;
+                _context2.t3 = _context2["catch"](0);
+                return _context2.abrupt("return", handleOperationError(_context2.t3, catchHandler));
+              case 42:
               case "end":
                 return _context2.stop();
             }
-          }, _callee2, null, [[0, 47]]);
+          }, _callee2, null, [[0, 39]]);
         }));
         return function (_x2) {
           return _ref8.apply(this, arguments);

package/lib/backend/index.d.ts

@@ -2,4 +2,5 @@ export * from "./actions/index.js";
 export * from "./route-operation/index.js";
 export * from "./schemas/index.js";
 export * from "./errors.js";
+export * from "./response-headers.js";
 export * from "./scope.js";

package/lib/backend/index.js

@@ -20,6 +20,7 @@ __reExport(backend_exports, require("./actions"), module.exports);
 __reExport(backend_exports, require("./route-operation"), module.exports);
 __reExport(backend_exports, require("./schemas"), module.exports);
 __reExport(backend_exports, require("./errors"), module.exports);
+__reExport(backend_exports, require("./response-headers"), module.exports);
 __reExport(backend_exports, require("./scope"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -27,5 +28,6 @@ __reExport(backend_exports, require("./scope"), module.exports);
   ...require("./route-operation"),
   ...require("./schemas"),
   ...require("./errors"),
+  ...require("./response-headers"),
   ...require("./scope")
 });

package/lib/backend/response-headers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 记一个响应头，等这次请求出结果时一起发出去。
+ *
+ * @param owner 这次请求的会话对象 —— 处理器收到的那个 session（本库把 getSession 的返回值
+ *   原样传给处理器，所以业务那边手上的就是它）。传 undefined 等于不记。
+ */
+export declare function setResponseHeader(owner: unknown, name: string, value: string): void;
+/**
+ * 把这次请求攒下的头写进已经建好的那条响应。**工厂出口用**。
+ *
+ * 为什么是「建好之后再写」而不是建的时候一起传：TypedNextResponse.json 的第二个参数只收
+ * status（见 next-rest-framework 的类型），而响应对象本身的 headers 是可写的。
+ */
+export declare function withResponseHeaders<T extends {
+    headers: Headers;
+}>(response: T, owner: unknown): T;

package/lib/backend/response-headers.js

@@ -0,0 +1,57 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/response-headers.ts
+var response_headers_exports = {};
+__export(response_headers_exports, {
+  setResponseHeader: () => setResponseHeader,
+  withResponseHeaders: () => withResponseHeaders
+});
+module.exports = __toCommonJS(response_headers_exports);
+var pending = /* @__PURE__ */ new WeakMap();
+function setResponseHeader(owner, name, value) {
+  if (!isKey(owner)) {
+    return;
+  }
+  pending.set(owner, { ...pending.get(owner), [name]: value });
+}
+function isKey(owner) {
+  return typeof owner === "object" && owner !== null;
+}
+function takeResponseHeaders(owner) {
+  if (!isKey(owner)) {
+    return void 0;
+  }
+  const headers = pending.get(owner);
+  if (headers) {
+    pending.delete(owner);
+  }
+  return headers;
+}
+function withResponseHeaders(response, owner) {
+  const extra = takeResponseHeaders(owner);
+  for (const [name, value] of Object.entries(extra ?? {})) {
+    response.headers.set(name, value);
+  }
+  return response;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  setResponseHeader,
+  withResponseHeaders
+});

package/lib/backend/route-operation/read-operation-core.js

@@ -27,6 +27,7 @@ var import_next_rest_framework = require("next-rest-framework");
 var import_schemas = require("../schemas");
 var import_open_api_operation = require("./open-api-operation");
 var import_operation_common = require("./operation-common");
+var import_response_headers = require("../response-headers");
 function createGetOperationFactory({
   createAction,
   getTableName
@@ -87,7 +88,10 @@ function createGetOperationFactory({
           req
         });
       }
-      return import_next_rest_framework.TypedNextResponse.json(result, { status: 200 });
+      return (0, import_response_headers.withResponseHeaders)(
+        import_next_rest_framework.TypedNextResponse.json(result, { status: 200 }),
+        session
+      );
     } catch (error) {
       return (0, import_operation_common.handleOperationError)(error, catchHandler);
     }
@@ -152,9 +156,10 @@ function createGetListOperationFactory({
           req
         });
       }
-      return import_next_rest_framework.TypedNextResponse.json(result, {
-        status: 200
-      });
+      return (0, import_response_headers.withResponseHeaders)(
+        import_next_rest_framework.TypedNextResponse.json(result, { status: 200 }),
+        session
+      );
     } catch (error) {
       return (0, import_operation_common.handleOperationError)(error, catchHandler);
     }

package/lib/backend/route-operation/write-operation-core.js

@@ -29,6 +29,7 @@ var import_zod = require("zod");
 var import_open_api_operation = require("./open-api-operation");
 var import_operation_common = require("./operation-common");
 var import_scope = require("../scope");
+var import_response_headers = require("../response-headers");
 function createPostOperationFactory({
   createAction,
   getTableName
@@ -93,7 +94,10 @@ function createPostOperationFactory({
         },
         req
       }) : raw;
-      return import_next_rest_framework.TypedNextResponse.json(data, { status: 200 });
+      return (0, import_response_headers.withResponseHeaders)(
+        import_next_rest_framework.TypedNextResponse.json(data, { status: 200 }),
+        session
+      );
     } catch (error) {
       return (0, import_operation_common.handleOperationError)(error, catchHandler);
     }
@@ -130,7 +134,6 @@ function createPutOperationFactory({
       status: 200
     }
   ]).handler(async (req) => {
-    var _a;
     try {
       const loadSession = (0, import_operation_common.sessionLoader)(getSession, req);
       const { scope } = await (0, import_operation_common.resolveAccess)({
@@ -142,7 +145,8 @@ function createPutOperationFactory({
       const extraBody = await (setBody == null ? void 0 : setBody(
         req
       )) || {};
-      const editorId = (_a = await loadSession()) == null ? void 0 : _a.userId;
+      const session = await loadSession();
+      const editorId = session == null ? void 0 : session.userId;
       const params = { ...body, ...extraBody, editorId };
       const raw = table && db ? await createAction({
         bodySchema: schemas.body,
@@ -159,7 +163,10 @@ function createPutOperationFactory({
         },
         req
       }) : raw;
-      return import_next_rest_framework.TypedNextResponse.json(data, { status: 200 });
+      return (0, import_response_headers.withResponseHeaders)(
+        import_next_rest_framework.TypedNextResponse.json(data, { status: 200 }),
+        session
+      );
     } catch (error) {
       return (0, import_operation_common.handleOperationError)(error, catchHandler);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai0x0/utils",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"