@weiliang0121/capix-diagnostics 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei.liang (https://github.com/weiliang0121)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @weiliang0121/capix-diagnostics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bounded diagnostics and persistence failures for CAPiX.
+
+ES modules and TypeScript declarations. Requires Node.js 22.23.2 or newer.
+
+```sh
+npm install @weiliang0121/capix-diagnostics
+```
+
+## Public entry points
+
+- `@weiliang0121/capix-diagnostics`
+
+This package is part of CAPiX. The npm distribution contains compiled JavaScript, type declarations, and this package's MIT license. Reference services and client applications are not included in this package or the initial npm release.
+
+## License
+
+MIT. Copyright (c) 2026 wei.liang. See [LICENSE](LICENSE).

package/dist/detail.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimeErrorDetail } from '@weiliang0121/capix-contracts';
+import { ErrorTraversal } from './traversal.js';
+type NestedErrorConverter = (value: unknown, depth: number) => RuntimeErrorDetail;
+export declare function formatDetail(value: unknown, traversal: ErrorTraversal, depth: number, formatNestedError: NestedErrorConverter): RuntimeErrorDetail;
+export declare function formatText(value: string): string;
+export {};

package/dist/detail.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isArray,isFinite}from"es-toolkit/compat";import{isNativeError}from"node:util/types";import{isBoolean,isDate,isMap,isNull,isNumber,isSet,isString,isSymbol,isUndefined}from"es-toolkit/predicate";import{formatLimits}from"./traversal.js";function formatDetail(value,traversal,depth,formatNestedError){if(!traversal.consume(depth))return"[Truncated: error conversion limit]";if(value===null||typeof value!="object")return formatScalar(value);if(traversal.contains(value))return"[Circular reference]";try{if(isNativeError(value))return formatNestedError(value,depth+1);const convert=__name(item=>formatDetail(item,traversal,depth+1,formatNestedError),"convert");return traversal.within(value,()=>formatObject(value,convert))}catch{return"[Uninspectable value]"}}__name(formatDetail,"formatDetail");function formatText(value){return value.length>formatLimits.string?`${value.slice(0,formatLimits.string)}[Truncated: string limit]`:value}__name(formatText,"formatText");function formatScalar(value){return isNull(value)||isBoolean(value)?value:isString(value)?formatText(value):isNumber(value)?isFinite(value)?value:`[Number: ${value}]`:isUndefined(value)?"[Undefined]":typeof value=="bigint"?formatText(`[BigInt: ${value}]`):isSymbol(value)?formatText(`[Symbol: ${value.description??""}]`):"[Function]"}__name(formatScalar,"formatScalar");function formatObject(value,convert){return isDate(value)?formatDate(value):isMap(value)?{type:"Map",entries:formatEntries(Map.prototype.entries.call(value),([key,item])=>[convert(key),convert(item)])}:isSet(value)?{type:"Set",entries:formatEntries(Set.prototype.values.call(value),convert)}:isArray(value)?formatArray(value,convert):formatProperties(value,convert)}__name(formatObject,"formatObject");function formatDate(value){const time=Date.prototype.getTime.call(value);return{type:"Date",value:isFinite(time)?new Date(time).toISOString():"[Invalid Date]"}}__name(formatDate,"formatDate");function formatEntries(values,convert){const entries=[];for(const value of values){if(entries.length>=formatLimits.entries){entries.push("[Truncated: entry limit]");break}entries.push(convert(value))}return entries}__name(formatEntries,"formatEntries");function formatArray(value,convert){const items=[];for(let i=0;i<Math.min(value.length,formatLimits.entries);i++)items.push(convert(readOwnValue(value,String(i))));return value.length>formatLimits.entries&&items.push("[Truncated: entry limit]"),items}__name(formatArray,"formatArray");function formatProperties(value,convert){const result=Object.create(null),keys=Object.keys(value);for(const key of keys.slice(0,formatLimits.entries))result[key]=convert(readOwnValue(value,key));return keys.length>formatLimits.entries&&(result["[Truncated]"]="Entry limit reached"),result}__name(formatProperties,"formatProperties");function readOwnValue(value,key){const descriptor=Object.getOwnPropertyDescriptor(value,key);return descriptor&&"value"in descriptor?descriptor.value:descriptor?"[Accessor not evaluated]":void 0}__name(readOwnValue,"readOwnValue");export{formatDetail,formatText};

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+import { ErrorTraversal } from './traversal.js';
+export declare function formatError(error: unknown, traversal: ErrorTraversal, depth?: number): RuntimeErrorValue;

package/dist/format.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{isArray}from"es-toolkit/compat";import{isNativeError,isProxy}from"node:util/types";import{zipObject}from"es-toolkit/array";import{isError,isString,isUndefined}from"es-toolkit/predicate";import{formatLimits}from"./traversal.js";import{formatDetail,formatText}from"./detail.js";const errorFieldNames=["code","message","name","stack","detail","cause","errors"],nativeDOMGetters=new Set(typeof DOMException>"u"?[]:["name","message","code"].map(key=>Object.getOwnPropertyDescriptor(DOMException.prototype,key)?.get).filter(get=>get!==void 0)),nativeStackGetter=Object.getOwnPropertyDescriptor(new Error,"stack")?.get,nativeStackFormatter=Object.getOwnPropertyDescriptor(Error,"prepareStackTrace")?.value;function formatError(error,traversal,depth=0){if(!traversal.consume(depth))return{code:"ERROR_TRUNCATED",message:"[Truncated: error conversion limit]"};if(error===null||typeof error!="object")return formatThrownValue(error,traversal,depth);if(isProxy(error))return{code:"UNREADABLE_ERROR",message:"[Uninspectable thrown object]"};if(traversal.contains(error))return{code:"CIRCULAR_ERROR",message:"[Circular error reference]"};try{return!isNativeError(error)&&!isError(error)?formatThrownValue(error,traversal,depth):traversal.within(error,()=>formatFields(readFields(error),traversal,depth))}catch{return{code:"UNREADABLE_ERROR",message:"[Uninspectable thrown object]"}}}__name(formatError,"formatError");function formatThrownValue(value,traversal,depth){return{code:"NON_ERROR_THROWN",message:"A non-Error value was thrown",detail:formatContent(value,traversal,depth+1)}}__name(formatThrownValue,"formatThrownValue");function readFields(error){return zipObject(errorFieldNames,errorFieldNames.map(key=>readProperty(error,key)))}__name(readFields,"readFields");function formatFields(fields,traversal,depth){return{code:isString(fields.code)?formatText(fields.code):isArray(fields.errors)?"AGGREGATE_ERROR":"INTERNAL_ERROR",message:isString(fields.message)?formatText(fields.message):"Error message unavailable",name:isString(fields.name)?formatText(fields.name):"Error",...isString(fields.stack)?{stack:formatText(fields.stack)}:{},...isUndefined(fields.detail)?{}:{detail:formatContent(fields.detail,traversal,depth+1)},...isUndefined(fields.cause)?{}:{cause:formatError(fields.cause,traversal,depth+1)},...isUndefined(fields.errors)?{}:{errors:formatMembers(fields.errors,traversal,depth+1)}}}__name(formatFields,"formatFields");function formatContent(value,traversal,depth){return formatDetail(value,traversal,depth,(error,nestedDepth)=>formatError(error,traversal,nestedDepth))}__name(formatContent,"formatContent");function formatMembers(members,traversal,depth){if(isProxy(members)||!isArray(members))return[{code:"UNREADABLE_ERROR",message:"[Unreadable aggregate members]"}];const errors=[];for(let i=0;i<Math.min(members.length,formatLimits.entries);i++)errors.push(formatError(readProperty(members,String(i)),traversal,depth));return members.length>formatLimits.entries&&errors.push({code:"ERROR_TRUNCATED",message:"[Truncated: aggregate member limit]"}),errors}__name(formatMembers,"formatMembers");function readProperty(value,key){try{let current=value;for(let depth=0;current&&depth<=formatLimits.depth;depth++){if(isProxy(current))return"[Unreadable property]";const descriptor=Object.getOwnPropertyDescriptor(current,key);if(descriptor){if("value"in descriptor)return descriptor.value;if(descriptor.get&&nativeDOMGetters.has(descriptor.get))return descriptor.get.call(value);if(key==="stack"&&descriptor.get&&descriptor.get===nativeStackGetter&&safeErrorText(value,"name")&&safeErrorText(value,"message")){const formatter=Object.getOwnPropertyDescriptor(Error,"prepareStackTrace");if(formatter&&"value"in formatter&&formatter.value===nativeStackFormatter)return descriptor.get.call(value)}return"[Accessor not evaluated]"}current=Object.getPrototypeOf(current)}return current?"[Truncated: prototype limit]":void 0}catch{return"[Unreadable property]"}}__name(readProperty,"readProperty");function safeErrorText(value,key){let current=value;for(let depth=0;current&&depth<=formatLimits.depth;depth++){if(isProxy(current))return!1;const descriptor=Object.getOwnPropertyDescriptor(current,key);if(descriptor)return"value"in descriptor&&(typeof descriptor.value=="string"||descriptor.value===void 0);current=Object.getPrototypeOf(current)}return current===null}__name(safeErrorText,"safeErrorText");export{formatError};

package/dist/helper.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeErrorValue } from '@weiliang0121/capix-contracts';
+export declare class RuntimeErrorHelper {
+    static format(error: unknown): RuntimeErrorValue;
+}

package/dist/helper.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{ErrorTraversal,formatLimits}from"./traversal.js";import{formatError}from"./format.js";class RuntimeErrorHelper{static{__name(this,"RuntimeErrorHelper")}static format(error){return formatError(error,new ErrorTraversal(formatLimits))}}export{RuntimeErrorHelper};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { RuntimeError } from '@weiliang0121/capix-contracts';
+export type { RuntimeErrorValue, RuntimeErrorDetail } from '@weiliang0121/capix-contracts';
+export { PersistenceError } from './persistence.js';
+export { RuntimeErrorHelper } from './helper.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+import{RuntimeError}from"@weiliang0121/capix-contracts";import{PersistenceError}from"./persistence.js";import{RuntimeErrorHelper}from"./helper.js";export{PersistenceError,RuntimeError,RuntimeErrorHelper};

package/dist/persistence.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeError } from '@weiliang0121/capix-contracts';
+export declare class PersistenceError extends RuntimeError {
+    readonly operation: string;
+    constructor(operation: string, cause: unknown);
+}

package/dist/persistence.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});import{RuntimeError}from"@weiliang0121/capix-contracts";class PersistenceError extends RuntimeError{static{__name(this,"PersistenceError")}operation;constructor(operation,cause){super("PERSISTENCE_FAILED",`Required persistence failed: ${operation}`,void 0,{cause}),this.operation=operation}}export{PersistenceError};

package/dist/traversal.d.ts

@@ -0,0 +1,18 @@
+export declare const formatLimits: {
+    readonly depth: 12;
+    readonly values: 2048;
+    readonly entries: 100;
+    readonly string: 16384;
+};
+export declare class ErrorTraversal {
+    private readonly limits;
+    private readonly ancestors;
+    private remaining;
+    constructor(limits: {
+        depth: number;
+        values: number;
+    });
+    consume(depth: number): boolean;
+    contains(value: object): boolean;
+    within<Result>(value: object, convert: () => Result): Result;
+}

package/dist/traversal.js

@@ -0,0 +1,2 @@
+/*! MIT License | Copyright (c) 2026 wei.liang | See LICENSE */
+var __defProp=Object.defineProperty;var __name=(target,value)=>__defProp(target,"name",{value,configurable:!0});const formatLimits={depth:12,values:2048,entries:100,string:16384};class ErrorTraversal{static{__name(this,"ErrorTraversal")}limits;ancestors=new Set;remaining;constructor(limits){this.limits=limits,this.remaining=limits.values}consume(depth){return depth<=this.limits.depth&&this.remaining-- >0}contains(value){return this.ancestors.has(value)}within(value,convert){this.ancestors.add(value);try{return convert()}finally{this.ancestors.delete(value)}}}export{ErrorTraversal,formatLimits};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@weiliang0121/capix-diagnostics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "es-toolkit": "1.52.0",
+    "@weiliang0121/capix-contracts": "0.2.0"
+  },
+  "description": "Bounded diagnostics and persistence failures for CAPiX.",
+  "license": "MIT",
+  "author": "wei.liang (https://github.com/weiliang0121)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiliang0121/capix.git",
+    "directory": "packages/diagnostics"
+  },
+  "engines": {
+    "node": ">=22.23.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/test/run.mjs --package ."
+  }
 }