@ecosy/core 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,16 +1,7 @@
-export * from "./env";
-export * from "./http";
-export * from "./logger";
-export * from "./searchify";
 export * from "./serialize";
-export * from "./slugify";
 export * from "./subscriber";
 export * from "./utilities";
-export type * from "./http";
-export type * from "./logger";
-export type * from "./searchify";
 export type * from "./serialize";
-export type * from "./slugify";
 export type * from "./subscriber";
 export type * from "./utilities";
 export type * from "./types";

package/dist/index.js

@@ -1 +1 @@
-"use strict";var e=require("./env.js"),t=require("./http/array.js"),r=require("./http/client.js"),i=require("./http/endpoint.js"),s=require("./http/fetcher.js"),p=require("./http/http-static.js"),o=require("./http/http.js"),u=require("./http/init.js"),l=require("./http/method.js"),a=require("./http/plugins/logger.js"),x=require("./http/plugins/dedupe.js"),c=require("./http/plugins/cache.js"),n=require("./http/utils.js"),j=require("./http/xml.js"),g=require("./http/http-core.js"),q=require("./logger.js");require("./searchify.js");var h=require("./serialize.js"),b=require("./slugify.js"),f=require("./subscriber.js"),d=require("./utilities/clone.js"),m=require("./utilities/defer.js"),E=require("./utilities/filelist.js"),y=require("./utilities/flatten.js"),F=require("./utilities/freeze.js"),H=require("./utilities/get.js"),M=require("./utilities/is-equal.js"),O=require("./utilities/is-function.js"),S=require("./utilities/object.js"),A=require("./utilities/merge.js"),L=require("./utilities/formdata.js"),R=require("./utilities/sanitize-mime.js"),T=require("./utilities/string.js");exports.getEnv=e.getEnv,exports.asArray=t.asArray,exports.createClient=r.createClient,exports.Endpoint=i.Endpoint,exports.Fetcher=s.Fetcher,exports.HttpStatic=p.HttpStatic,exports.Http=o.Http,exports.getHttpInitSlice=u.getHttpInitSlice,exports.Methods=l.Methods,exports.Uploads=l.Uploads,exports.loggerPlugin=a.loggerPlugin,exports.dedupePlugin=x.dedupePlugin,exports.cachePlugin=c.cachePlugin,exports.HttpUtils=n.HttpUtils,exports.HttpXML=j.HttpXML,exports.HttpCore=g.HttpCore,exports.Logger=q.Logger,exports.Serialize=h.Serialize,exports.DEFAULT_TRANSFORMER=b.DEFAULT_TRANSFORMER,exports.slugify=b.slugify,exports.Subscriber=f.Subscriber,exports.clone=d.clone,exports.defer=m.defer,exports.deferAsync=m.deferAsync,exports.isFileList=E.isFileList,exports.escapeRegexKey=y.escapeRegexKey,exports.flatten=y.flatten,exports.flattenToArray=y.flattenToArray,exports.freeze=F.freeze,exports.get=H.get,exports.isEqual=M.isEqual,exports.isFunction=O.isFunction,exports.hasOwnProperty=S.hasOwnProperty,exports.isComplexObject=S.isComplexObject,exports.isLiteralObject=S.isLiteralObject,exports.isObject=S.isObject,exports.isObjectable=S.isObjectable,exports.merge=A.merge,exports.isFormData=L.isFormData,exports.objectToFormData=L.objectToFormData,exports.MIME_REGEX=R.MIME_REGEX,exports.sanitizeMime=R.sanitizeMime,exports.pascalToKebab=T.pascalToKebab,exports.toString=T.toString,exports.ucfirst=T.ucfirst;
+"use strict";var e=require("./serialize/index.js"),i=require("./subscriber.js"),r=require("./utilities/clone.js"),s=require("./utilities/defer.js"),t=require("./utilities/filelist.js"),o=require("./utilities/flatten.js"),u=require("./utilities/freeze.js"),l=require("./utilities/get.js"),a=require("./utilities/is-equal.js"),p=require("./utilities/is-function.js"),x=require("./utilities/object.js"),j=require("./utilities/merge.js"),n=require("./utilities/formdata.js"),c=require("./utilities/sanitize-mime.js"),q=require("./utilities/searchify.js"),f=require("./utilities/slugify.js"),b=require("./utilities/string.js"),g=require("./serialize/json.js"),m=require("./serialize/primitive.js"),y=require("./serialize/url.js"),z=require("./serialize/interpolate.js"),E=require("./serialize/query-string.js");exports.Serialize=e.Serialize,exports.Subscriber=i.Subscriber,exports.clone=r.clone,exports.defer=s.defer,exports.deferAsync=s.deferAsync,exports.isFileList=t.isFileList,exports.escapeRegexKey=o.escapeRegexKey,exports.flatten=o.flatten,exports.flattenToArray=o.flattenToArray,exports.freeze=u.freeze,exports.get=l.get,exports.isEqual=a.isEqual,exports.isFunction=p.isFunction,exports.hasOwnProperty=x.hasOwnProperty,exports.isComplexObject=x.isComplexObject,exports.isLiteralObject=x.isLiteralObject,exports.isObject=x.isObject,exports.isObjectable=x.isObjectable,exports.merge=j.merge,exports.isFormData=n.isFormData,exports.objectToFormData=n.objectToFormData,exports.MIME_REGEX=c.MIME_REGEX,exports.sanitizeMime=c.sanitizeMime,exports.searchify=q.searchify,exports.DEFAULT_TRANSFORMER=f.DEFAULT_TRANSFORMER,exports.slugify=f.slugify,exports.pascalToKebab=b.pascalToKebab,exports.toString=b.toString,exports.ucfirst=b.ucfirst,exports.Json=g.Json,exports.Primitive=m.Primitive,exports.Url=y.Url,exports.interpolate=z.interpolate,exports.queryString=E.queryString;

package/dist/index.mjs

@@ -1 +1 @@
-export{getEnv}from"./env.mjs";export{asArray}from"./http/array.mjs";export{createClient}from"./http/client.mjs";export{Endpoint}from"./http/endpoint.mjs";export{Fetcher}from"./http/fetcher.mjs";export{HttpStatic}from"./http/http-static.mjs";export{Http}from"./http/http.mjs";export{getHttpInitSlice}from"./http/init.mjs";export{Methods,Uploads}from"./http/method.mjs";export{loggerPlugin}from"./http/plugins/logger.mjs";export{dedupePlugin}from"./http/plugins/dedupe.mjs";export{cachePlugin}from"./http/plugins/cache.mjs";export{HttpUtils}from"./http/utils.mjs";export{HttpXML}from"./http/xml.mjs";export{HttpCore}from"./http/http-core.mjs";export{Logger}from"./logger.mjs";import"./searchify.mjs";export{Serialize}from"./serialize.mjs";export{DEFAULT_TRANSFORMER,slugify}from"./slugify.mjs";export{Subscriber}from"./subscriber.mjs";export{clone}from"./utilities/clone.mjs";export{defer,deferAsync}from"./utilities/defer.mjs";export{isFileList}from"./utilities/filelist.mjs";export{escapeRegexKey,flatten,flattenToArray}from"./utilities/flatten.mjs";export{freeze}from"./utilities/freeze.mjs";export{get}from"./utilities/get.mjs";export{isEqual}from"./utilities/is-equal.mjs";export{isFunction}from"./utilities/is-function.mjs";export{hasOwnProperty,isComplexObject,isLiteralObject,isObject,isObjectable}from"./utilities/object.mjs";export{merge}from"./utilities/merge.mjs";export{isFormData,objectToFormData}from"./utilities/formdata.mjs";export{MIME_REGEX,sanitizeMime}from"./utilities/sanitize-mime.mjs";export{pascalToKebab,toString,ucfirst}from"./utilities/string.mjs";
+export{Serialize}from"./serialize/index.mjs";export{Subscriber}from"./subscriber.mjs";export{clone}from"./utilities/clone.mjs";export{defer,deferAsync}from"./utilities/defer.mjs";export{isFileList}from"./utilities/filelist.mjs";export{escapeRegexKey,flatten,flattenToArray}from"./utilities/flatten.mjs";export{freeze}from"./utilities/freeze.mjs";export{get}from"./utilities/get.mjs";export{isEqual}from"./utilities/is-equal.mjs";export{isFunction}from"./utilities/is-function.mjs";export{hasOwnProperty,isComplexObject,isLiteralObject,isObject,isObjectable}from"./utilities/object.mjs";export{merge}from"./utilities/merge.mjs";export{isFormData,objectToFormData}from"./utilities/formdata.mjs";export{MIME_REGEX,sanitizeMime}from"./utilities/sanitize-mime.mjs";export{searchify}from"./utilities/searchify.mjs";export{DEFAULT_TRANSFORMER,slugify}from"./utilities/slugify.mjs";export{pascalToKebab,toString,ucfirst}from"./utilities/string.mjs";export{Json}from"./serialize/json.mjs";export{Primitive}from"./serialize/primitive.mjs";export{Url}from"./serialize/url.mjs";export{interpolate}from"./serialize/interpolate.mjs";export{queryString}from"./serialize/query-string.mjs";

package/dist/serialize/index.d.ts

@@ -0,0 +1,62 @@
+import { interpolate } from "./interpolate";
+export * from "./types";
+export { interpolate } from "./interpolate";
+export { Json } from "./json";
+export { Primitive } from "./primitive";
+export { queryString } from "./query-string";
+export { Url } from "./url";
+/**
+ * Centralized serialization engine and type-guard toolkit.
+ * Addresses common pitfalls of `JSON.stringify`/`JSON.parse` — BigInt safety,
+ * Date preservation, undefined stripping, and safe URL encoding/decoding.
+ *
+ * This is the convenience surface: it gathers every part under one name.
+ * Referencing it keeps all of them, because a class is a single binding and a
+ * bundler cannot drop half of one. Code that cares about what it ships should
+ * import the part it uses instead — each lives in its own module, so nothing
+ * else comes with it:
+ *
+ * ```ts
+ * import { Primitive } from "@ecosy/core/serialize/primitive";
+ * import { queryString } from "@ecosy/core/serialize/query-string";
+ * ```
+ *
+ * The two are the same objects, so mixing them is free.
+ *
+ * @example
+ * ```ts
+ * Serialize.JSON.stringify({ date: new Date(), big: 123n });
+ * Serialize.JSON.parse<User>(jsonText);
+ * Serialize.URL.encode("hello world");
+ * Serialize.queryString.stringify({ page: 1, tags: ["a", "b"] });
+ * ```
+ */
+export declare class Serialize {
+    static readonly interpolate: typeof interpolate;
+    /** Type guards and deep normalization utilities. */
+    static readonly Primitive: {
+        readonly isString: (value: unknown) => value is string;
+        readonly isNumber: (value: unknown) => value is number;
+        readonly isBoolean: (value: unknown) => value is boolean;
+        readonly isPrimitive: (value: unknown) => value is import("./types").PrimitiveValue;
+        readonly isDate: (value: unknown) => value is Date;
+        readonly isPlainObject: (value: unknown) => value is import("..").LiteralObject;
+        readonly normalize: <T, R = unknown>(data: T) => R;
+    };
+    /** Safe JSON stringify/parse that never throws. */
+    static readonly JSON: {
+        readonly stringify: (value: unknown, space?: number) => string;
+        readonly parse: <T = unknown>(text: string, reviver?: ((this: any, key: string, value: any) => any) | undefined) => T | null;
+    };
+    /** URL encoding/decoding with malformed-character recovery. */
+    static readonly URL: {
+        readonly encode: (value: string, component?: boolean | ((value: string) => string)) => string;
+        readonly decode: (value: string, component?: boolean | ((value: string) => string)) => string;
+        readonly build: (uri: string, params?: Record<string, import("./types").PrimitiveValue> | null) => string;
+    };
+    /** Query string parse/stringify with configurable array formats. */
+    static readonly queryString: {
+        readonly parse: (query: string) => Record<string, string>;
+        readonly stringify: (params: Record<string, unknown>, options?: import("./types").SerializeQueryOptions) => string;
+    };
+}

package/dist/serialize/index.js

@@ -0,0 +1 @@
+"use strict";var r=require("./interpolate.js"),e=require("./json.js"),i=require("./primitive.js"),t=require("./query-string.js"),s=require("./url.js");class o{}o.interpolate=r.interpolate,o.Primitive=i.Primitive,o.JSON=e.Json,o.URL=s.Url,o.queryString=t.queryString,exports.interpolate=r.interpolate,exports.Json=e.Json,exports.Primitive=i.Primitive,exports.queryString=t.queryString,exports.Url=s.Url,exports.Serialize=o;

package/dist/serialize/index.mjs

@@ -0,0 +1 @@
+import{interpolate as r}from"./interpolate.mjs";import{Json as m}from"./json.mjs";import{Primitive as i}from"./primitive.mjs";import{queryString as o}from"./query-string.mjs";import{Url as t}from"./url.mjs";class e{}e.interpolate=r,e.Primitive=i,e.JSON=m,e.URL=t,e.queryString=o;export{m as Json,i as Primitive,e as Serialize,t as Url,r as interpolate,o as queryString};

package/dist/serialize/interpolate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Interpolates `{key}` placeholders in a string using deep path resolution via {@link get}.
+ * Objects are silently replaced with empty strings to avoid `[object Object]`.
+ *
+ * @param pattern - Template string with `{key}` or `{path.to.key}` placeholders.
+ * @param params - Data object or array to resolve values from.
+ * @returns The interpolated string.
+ */
+export declare function interpolate(pattern: string, params?: Record<string, unknown> | Array<unknown>): string;
+/** Type guards and deep normalization utilities. */

package/dist/serialize/interpolate.js

@@ -0,0 +1 @@
+"use strict";var t=require("../utilities/get.js");exports.interpolate=function(e,r={}){return e&&"string"==typeof e&&e.trim().length&&e.includes("{")&&e.includes("}")?e.replace(/\{([a-zA-Z0-9_.-]+)\}/g,(e,i)=>{const n=t.get(r,i);return null==n||"object"==typeof n?"":String(n)}):e};

package/dist/serialize/interpolate.mjs

@@ -0,0 +1 @@
+import{get as t}from"../utilities/get.mjs";function e(e,n={}){return e&&"string"==typeof e&&e.trim().length&&e.includes("{")&&e.includes("}")?e.replace(/\{([a-zA-Z0-9_.-]+)\}/g,(e,r)=>{const i=t(n,r);return null==i||"object"==typeof i?"":String(i)}):e}export{e as interpolate};

package/dist/serialize/json.d.ts

@@ -0,0 +1,3 @@
+import type { SerializeJSON } from "./types";
+/** Safe JSON stringify/parse that never throws. */
+export declare const Json: SerializeJSON;

package/dist/serialize/json.js

@@ -0,0 +1 @@
+"use strict";var r=require("../utilities/freeze.js"),e=require("./primitive.js");const t=r.freeze({stringify:(r,t)=>{var i;try{const n=e.Primitive.normalize(r);return null!==(i=JSON.stringify(n,null,t))&&void 0!==i?i:""}catch(r){return""}},parse:(r,e)=>{if(!r)return null;try{return JSON.parse(r,e)}catch(r){return null}}});exports.Json=t;

package/dist/serialize/json.mjs

@@ -0,0 +1 @@
+import{freeze as r}from"../utilities/freeze.mjs";import{Primitive as t}from"./primitive.mjs";const i=r({stringify:(r,i)=>{var e;try{const n=t.normalize(r);return null!==(e=JSON.stringify(n,null,i))&&void 0!==e?e:""}catch(r){return""}},parse:(r,t)=>{if(!r)return null;try{return JSON.parse(r,t)}catch(r){return null}}});export{i as Json};

package/dist/serialize/primitive.d.ts

@@ -0,0 +1,3 @@
+import type { SerializePrimitive } from "./types";
+/** Type guards and deep normalization utilities. */
+export declare const Primitive: SerializePrimitive;

package/dist/serialize/primitive.js

@@ -0,0 +1 @@
+"use strict";var i=require("../utilities/freeze.js"),e=require("../utilities/object.js"),t=require("../utilities/is-function.js");const r=i.freeze({isString:i=>"string"==typeof i,isNumber:i=>"number"==typeof i&&Number.isFinite(i),isBoolean:i=>"boolean"==typeof i,isPrimitive:i=>!e.isObjectable(i),isDate:i=>i instanceof Date&&!Number.isNaN(i.getTime()),isPlainObject:e.isLiteralObject,normalize(i){const s=r;if(s.isPrimitive(i))return"bigint"==typeof i?i.toString():i;if(s.isDate(i))return i.toISOString();if(Array.isArray(i))return i.map(i=>s.normalize(i));if(e.isLiteralObject(i)){const t={};for(const r in i)if(e.hasOwnProperty(i,r)){const e=i[r];void 0!==e&&(t[r]=s.normalize(e))}return t}return i&&e.hasOwnProperty(i,"toJSON")&&t.isFunction(i.toJSON)?i.toJSON():{}}});exports.Primitive=r;

package/dist/serialize/primitive.mjs

@@ -0,0 +1 @@
+import{freeze as i}from"../utilities/freeze.mjs";import{isLiteralObject as t,hasOwnProperty as e,isObjectable as r}from"../utilities/object.mjs";import{isFunction as o}from"../utilities/is-function.mjs";const n=i({isString:i=>"string"==typeof i,isNumber:i=>"number"==typeof i&&Number.isFinite(i),isBoolean:i=>"boolean"==typeof i,isPrimitive:i=>!r(i),isDate:i=>i instanceof Date&&!Number.isNaN(i.getTime()),isPlainObject:t,normalize(i){const r=n;if(r.isPrimitive(i))return"bigint"==typeof i?i.toString():i;if(r.isDate(i))return i.toISOString();if(Array.isArray(i))return i.map(i=>r.normalize(i));if(t(i)){const t={};for(const o in i)if(e(i,o)){const e=i[o];void 0!==e&&(t[o]=r.normalize(e))}return t}return i&&e(i,"toJSON")&&o(i.toJSON)?i.toJSON():{}}});export{n as Primitive};

package/dist/serialize/query-string.d.ts

@@ -0,0 +1,3 @@
+import type { SerializeQueryString } from "./types";
+/** Query string parse/stringify with configurable array formats. */
+export declare const queryString: SerializeQueryString;

package/dist/serialize/query-string.js

@@ -0,0 +1 @@
+"use strict";var r=require("../utilities/freeze.js"),e=require("./primitive.js"),t=require("./url.js");const i=r.freeze({parse(r){if(!r)return{};const e=r.startsWith("?")?r.slice(1):r,i={};return e.split("&").forEach(r=>{if(!r)return;const[e,s]=r.split("=");e&&(i[t.Url.decode(e)]=s?t.Url.decode(s):"")}),i},stringify(r,i={}){if(null===r||"object"!=typeof r)return"";const{arrayFormat:s="none",arrayFormatSeparator:o=",",skipNull:n=!1,skipEmptyString:l=!1,encode:a=!0,strict:u=!0,sort:c=!1}=i,p=r=>r.length>0&&/^[a-zA-Z0-9_\-.[\]]+$/.test(r),f=r=>a?t.Url.encode(r,a):r,$=[],y=(r,t)=>{if(Array.isArray(t)){if("comma"===s||"separator"===s){const e=t.filter(r=>null!=r&&""!==r);return void(e.length>0&&$.push(`${f(r)}=${f(e.map(String).join(o))}`))}t.forEach((e,t)=>{let i=r;"bracket"===s?i=`${r}[]`:"index"===s&&(i=`${r}[${t}]`),y(i,e)})}else if(e.Primitive.isPlainObject(t))for(const e in t)Object.prototype.hasOwnProperty.call(t,e)&&y(`${r}[${e}]`,t[e]);else null!=t?""!==t?"boolean"!=typeof t?e.Primitive.isDate(t)?$.push(`${f(r)}=${f(t.toISOString())}`):$.push(`${f(r)}=${f(String(t))}`):$.push(`${f(r)}=${t?"true":"false"}`):l||$.push(`${f(r)}=`):n||$.push(`${f(r)}=`)};let h=Object.keys(r);c&&(h="function"==typeof c?h.sort(c):h.sort());for(const e of h)u&&!p(e)||y(e,r[e]);return $.join("&")}});exports.queryString=i;

package/dist/serialize/query-string.mjs

@@ -0,0 +1 @@
+import{freeze as t}from"../utilities/freeze.mjs";import{Primitive as r}from"./primitive.mjs";import{Url as e}from"./url.mjs";const o=t({parse(t){if(!t)return{};const r=t.startsWith("?")?t.slice(1):t,o={};return r.split("&").forEach(t=>{if(!t)return;const[r,s]=t.split("=");r&&(o[e.decode(r)]=s?e.decode(s):"")}),o},stringify(t,o={}){if(null===t||"object"!=typeof t)return"";const{arrayFormat:s="none",arrayFormatSeparator:i=",",skipNull:n=!1,skipEmptyString:a=!1,encode:p=!0,strict:l=!0,sort:c=!1}=o,f=t=>t.length>0&&/^[a-zA-Z0-9_\-.[\]]+$/.test(t),u=t=>p?e.encode(t,p):t,m=[],$=(t,e)=>{if(Array.isArray(e)){if("comma"===s||"separator"===s){const r=e.filter(t=>null!=t&&""!==t);return void(r.length>0&&m.push(`${u(t)}=${u(r.map(String).join(i))}`))}e.forEach((r,e)=>{let o=t;"bracket"===s?o=`${t}[]`:"index"===s&&(o=`${t}[${e}]`),$(o,r)})}else if(r.isPlainObject(e))for(const r in e)Object.prototype.hasOwnProperty.call(e,r)&&$(`${t}[${r}]`,e[r]);else null!=e?""!==e?"boolean"!=typeof e?r.isDate(e)?m.push(`${u(t)}=${u(e.toISOString())}`):m.push(`${u(t)}=${u(String(e))}`):m.push(`${u(t)}=${e?"true":"false"}`):a||m.push(`${u(t)}=`):n||m.push(`${u(t)}=`)};let h=Object.keys(t);c&&(h="function"==typeof c?h.sort(c):h.sort());for(const r of h)l&&!f(r)||$(r,t[r]);return m.join("&")}});export{o as queryString};

package/dist/serialize/types.d.ts

@@ -0,0 +1,42 @@
+import type { Freezable, LiteralObject } from "../types/built-in";
+/** Anything JSON can hold as a leaf, plus the JS primitives that need special care. */
+export type PrimitiveValue = string | number | boolean | null | undefined | symbol | bigint;
+/** Options for {@link queryString.stringify}. */
+export interface SerializeQueryOptions {
+    /** Array serialization format. Defaults to `"none"`. */
+    arrayFormat?: "bracket" | "index" | "comma" | "separator" | "none";
+    /** Separator character when `arrayFormat` is `"separator"`. Defaults to `","`. */
+    arrayFormatSeparator?: string;
+    /** Skip keys whose value is `null` or `undefined`. */
+    skipNull?: boolean;
+    /** Skip keys whose value is an empty string. */
+    skipEmptyString?: boolean;
+    /** Whether to URL-encode keys and values, or a custom encoder function. Defaults to `true`. */
+    encode?: boolean | ((value: string) => string);
+    /** Reject keys with non-standard characters when `true`. Defaults to `true`. */
+    strict?: boolean;
+    /** Sort keys alphabetically, or provide a custom comparator. */
+    sort?: boolean | ((a: string, b: string) => number);
+}
+export type SerializePrimitive = Freezable<{
+    isString(value: unknown): value is string;
+    isNumber(value: unknown): value is number;
+    isBoolean(value: unknown): value is boolean;
+    isPrimitive(value: unknown): value is PrimitiveValue;
+    isDate(value: unknown): value is Date;
+    isPlainObject(value: unknown): value is LiteralObject;
+    normalize<T, R = unknown>(data: T): R;
+}>;
+export type SerializeJSON = Freezable<{
+    stringify: (value: unknown, space?: number) => string;
+    parse: <T = unknown>(text: string, reviver?: ((this: any, key: string, value: any) => any) | undefined) => T | null;
+}>;
+export type SerializeURL = Freezable<{
+    encode(value: string, component?: boolean | ((value: string) => string)): string;
+    decode(value: string, component?: boolean | ((value: string) => string)): string;
+    build(uri: string, params?: Record<string, PrimitiveValue> | null): string;
+}>;
+export type SerializeQueryString = Freezable<{
+    parse(query: string): Record<string, string>;
+    stringify(params: Record<string, unknown>, options?: SerializeQueryOptions): string;
+}>;

package/dist/serialize/url.d.ts

@@ -0,0 +1,3 @@
+import type { SerializeURL } from "./types";
+/** URL encoding/decoding with malformed-character recovery. */
+export declare const Url: SerializeURL;

package/dist/serialize/url.js

@@ -0,0 +1 @@
+"use strict";const e=require("../utilities/freeze.js").freeze({encode(e,r=!0){if(!e)return"";if("function"==typeof r)return r(e);try{return r?encodeURIComponent(e):encodeURI(e)}catch(t){const n=e.replace(/[\uD800-\uDFFF]/g,"");return r?encodeURIComponent(n):encodeURI(n)}},decode:(e,r=!0)=>{if(!e)return"";if("function"==typeof r)return r(e);const t=r?decodeURIComponent:decodeURI;return(r?e.replace(/\+/g,"%20"):e).replace(/(%[0-9A-F]{2})+/gi,e=>{try{return t(e)}catch(r){return e}})},build:(r,t)=>r?t&&"object"==typeof t?r.replace(/:([a-zA-Z\d_]+)/g,(r,n)=>{const o=t[n];return null==o?r:e.encode(String(o),!0)}):r:""});exports.Url=e;

package/dist/serialize/url.mjs

@@ -0,0 +1 @@
+import{freeze as e}from"../utilities/freeze.mjs";const n=e({encode(e,n=!0){if(!e)return"";if("function"==typeof n)return n(e);try{return n?encodeURIComponent(e):encodeURI(e)}catch(t){const r=e.replace(/[\uD800-\uDFFF]/g,"");return n?encodeURIComponent(r):encodeURI(r)}},decode:(e,n=!0)=>{if(!e)return"";if("function"==typeof n)return n(e);const t=n?decodeURIComponent:decodeURI;return(n?e.replace(/\+/g,"%20"):e).replace(/(%[0-9A-F]{2})+/gi,e=>{try{return t(e)}catch(n){return e}})},build:(e,t)=>e?t&&"object"==typeof t?e.replace(/:([a-zA-Z\d_]+)/g,(e,r)=>{const o=t[r];return null==o?e:n.encode(String(o),!0)}):e:""});export{n as Url};

package/dist/syhemo/collectors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where every number comes from.
+ *
+ * All of it is Node stdlib — perf_hooks, v8, os, process — plus two things the
+ * host feeds in: `recordHttpRequest` for traffic, and the `db` callback given
+ * to `Syhemo.start()`. Nothing here knows what framework is running above it.
+ *
+ * Two rules hold throughout, both from the Prometheus model:
+ *
+ *  - Values are in base units and are not rounded.
+ *  - Anything typed `counter` only ever grows. Collection runs on Syhemo's own
+ *    interval, so a scrape never mutates state and two scrapers never steal
+ *    each other's numbers.
+ */
+import type { Metric, SyhemoLogSource } from "./types";
+/**
+ * Records one finished request.
+ *
+ * @param latencyMs Duration in milliseconds — converted to seconds here, since
+ *                  callers time requests in ms and Prometheus wants seconds.
+ */
+export declare function recordHttpRequest(latencyMs: number): void;
+/** Registers the connectivity probe `Syhemo.start({ db })` was given. */
+export declare function setDbChecker(fn: (() => boolean) | null): void;
+export declare function collectMetrics(source: SyhemoLogSource): Metric[];

package/dist/syhemo/collectors.js

@@ -0,0 +1 @@
+"use strict";var node_perf_hooks=require("node:perf_hooks"),v8=require("v8"),os=require("os");function _interopNamespace(e){if(e&&e.__esModule)return e;var t=Object.create(null);return e&&Object.keys(e).forEach(function(o){if("default"!==o){var a=Object.getOwnPropertyDescriptor(e,o);Object.defineProperty(t,o,a.get?a:{enumerable:!0,get:function(){return e[o]}})}}),t.default=e,Object.freeze(t)}var v8__namespace=_interopNamespace(v8),os__namespace=_interopNamespace(os);const NS_PER_SECOND=1e9,MS_PER_SECOND=1e3;function collectMemory(){const e=process.memoryUsage();return[{name:"process_resident_memory_bytes",type:"gauge",help:"Resident set size in bytes.",value:e.rss},{name:"nodejs_external_memory_bytes",type:"gauge",help:"Memory used by C++ objects bound to JavaScript, in bytes.",value:e.external},{name:"nodejs_array_buffers_bytes",type:"gauge",help:"Memory allocated for ArrayBuffers and SharedArrayBuffers, in bytes.",value:e.arrayBuffers}]}let prevCpuUsage=null;function collectCpu(){var e,t;const o=os__namespace.cpus();let a=0;if(prevCpuUsage&&prevCpuUsage.length===o.length){let e=0,t=0;for(let a=0;a<o.length;a++){const l=prevCpuUsage[a].times,s=o[a].times,n=l.user+l.nice+l.sys+l.idle+l.irq;e+=s.user+s.nice+s.sys+s.idle+s.irq-n,t+=s.idle-l.idle}a=e>0?1-t/e:0}return prevCpuUsage=o,[{name:"process_cpu_usage_ratio",type:"gauge",help:"Share of CPU time spent non-idle since the previous collection, 0 to 1.",value:a},{name:"nodejs_cpu_count",type:"gauge",help:"Number of logical CPUs.",value:o.length},{name:"nodejs_cpu_info",type:"gauge",help:"CPU model, always 1.",labels:{model:null!==(t=null===(e=o[0])||void 0===e?void 0:e.model)&&void 0!==t?t:"unknown"},value:1}]}function collectHeap(){const e=v8__namespace.getHeapStatistics();return[{name:"nodejs_heap_size_total_bytes",type:"gauge",help:"Total V8 heap size in bytes.",value:e.total_heap_size},{name:"nodejs_heap_size_used_bytes",type:"gauge",help:"Used V8 heap size in bytes.",value:e.used_heap_size},{name:"nodejs_heap_size_limit_bytes",type:"gauge",help:"Ceiling V8 will grow the heap to, in bytes.",value:e.heap_size_limit},{name:"nodejs_malloced_memory_bytes",type:"gauge",help:"Memory malloc'd by V8, in bytes.",value:e.malloced_memory},{name:"nodejs_native_contexts",type:"gauge",help:"Live top-level contexts. A number that only grows indicates a leak.",value:e.number_of_native_contexts},{name:"nodejs_detached_contexts",type:"gauge",help:"Contexts detached but not yet garbage collected.",value:e.number_of_detached_contexts}]}function collectHandles(){var e,t,o,a,l,s;const n=null!==(t=null===(e=process._getActiveHandles)||void 0===e?void 0:e.call(process))&&void 0!==t?t:[],r=null!==(a=null===(o=process._getActiveRequests)||void 0===o?void 0:o.call(process))&&void 0!==a?a:[];let c=0,u=0;for(const e of n){const t=null!==(s=null===(l=null==e?void 0:e.constructor)||void 0===l?void 0:l.name)&&void 0!==s?s:"";"Timeout"===t||"Timer"===t||"Immediate"===t?c++:"Socket"!==t&&"TCP"!==t&&"TLSSocket"!==t||u++}return[{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"timer"},value:c},{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"socket"},value:u},{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"other"},value:n.length-c-u},{name:"nodejs_active_requests_total",type:"gauge",help:"Active libuv requests.",value:r.length}]}const TOP_MODULE_GROUPS=20;function collectModules(){var _a;try{const cache=eval("typeof require !== 'undefined' && require.cache")||{},keys=Object.keys(cache),groups=new Map;for(const e of keys){const t=e.match(/node_modules\/([^/]+)/),o=t?`node_modules/${t[1]}`:e.replace(process.cwd(),".");groups.set(o,(null!==(_a=groups.get(o))&&void 0!==_a?_a:0)+1)}const top=Array.from(groups.entries()).sort((e,t)=>t[1]-e[1]).slice(0,TOP_MODULE_GROUPS);return[{name:"nodejs_module_cache_entries",type:"gauge",help:"Entries in the CommonJS module cache.",value:keys.length},...top.map(([e,t])=>({name:"nodejs_module_cache_entries_by_group",type:"gauge",help:`Module cache entries per group, top ${TOP_MODULE_GROUPS}.`,labels:{group:e},value:t}))]}catch(e){return[{name:"nodejs_module_cache_entries",type:"gauge",help:"Entries in the CommonJS module cache.",value:0}]}}const histogram=node_perf_hooks.monitorEventLoopDelay({resolution:10});function collectEventLoop(){const e=0===histogram.count,t=t=>e||!Number.isFinite(t)?0:t/NS_PER_SECOND,o=[{name:"nodejs_eventloop_lag_mean_seconds",type:"gauge",help:"Mean event loop lag over the last interval.",value:t(histogram.mean)},{name:"nodejs_eventloop_lag_min_seconds",type:"gauge",help:"Minimum event loop lag over the last interval.",value:t(histogram.min)},{name:"nodejs_eventloop_lag_max_seconds",type:"gauge",help:"Maximum event loop lag over the last interval.",value:t(histogram.max)},{name:"nodejs_eventloop_lag_p99_seconds",type:"gauge",help:"99th percentile event loop lag over the last interval.",value:t(histogram.percentile(99))}];return histogram.reset(),o}histogram.enable();const LATENCY_BUCKETS=[.005,.01,.025,.05,.1,.25,.5,1,2.5,5,10];let httpTotal=0,httpDurationSum=0;const httpBuckets=new Array(LATENCY_BUCKETS.length+1).fill(0);function recordHttpRequest(e){const t=e/MS_PER_SECOND;httpTotal++,httpDurationSum+=t;for(let e=0;e<LATENCY_BUCKETS.length;e++)t<=LATENCY_BUCKETS[e]&&httpBuckets[e]++;httpBuckets[LATENCY_BUCKETS.length]++}function collectHttp(){const e=LATENCY_BUCKETS.map((e,t)=>({le:e,count:httpBuckets[t]}));return e.push({le:1/0,count:httpBuckets[LATENCY_BUCKETS.length]}),[{name:"http_requests_total",type:"counter",help:"Requests recorded since the process started.",value:httpTotal},{name:"http_request_duration_seconds",type:"histogram",help:"Request duration in seconds.",buckets:e,sum:httpDurationSum,count:httpTotal}]}let dbChecker=null;function setDbChecker(e){dbChecker=e}function collectDbPool(){return[{name:"db_pool_connected",type:"gauge",help:"1 when the database pool reports a connection, 0 otherwise.",value:dbChecker&&dbChecker()?1:0}]}function collectLogs(e){const t=e.counts(),o="Log entries written since the process started, by level.";return[{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"error"},value:t.errors},{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"warn"},value:t.warns},{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"other"},value:Math.max(0,t.total-t.errors-t.warns)}]}function collectSystem(){const[e,t,o]=os__namespace.loadavg(),a="System load average.";return[{name:"nodejs_version_info",type:"gauge",help:"Node.js version and platform, always 1.",labels:{version:process.version,platform:os__namespace.platform(),arch:os__namespace.arch()},value:1},{name:"system_memory_total_bytes",type:"gauge",help:"Total system memory in bytes.",value:os__namespace.totalmem()},{name:"system_memory_free_bytes",type:"gauge",help:"Free system memory in bytes.",value:os__namespace.freemem()},{name:"process_uptime_seconds",type:"gauge",help:"Seconds since the process started.",value:process.uptime()},{name:"system_load_average",type:"gauge",help:a,labels:{period:"1m"},value:e},{name:"system_load_average",type:"gauge",help:a,labels:{period:"5m"},value:t},{name:"system_load_average",type:"gauge",help:a,labels:{period:"15m"},value:o}]}function collectMetrics(e){return[...collectMemory(),...collectCpu(),...collectHeap(),...collectHandles(),...collectModules(),...collectEventLoop(),...collectHttp(),...collectDbPool(),...collectLogs(e),...collectSystem()]}exports.collectMetrics=collectMetrics,exports.recordHttpRequest=recordHttpRequest,exports.setDbChecker=setDbChecker;

package/dist/syhemo/collectors.mjs

@@ -0,0 +1 @@
+import{monitorEventLoopDelay}from"node:perf_hooks";import*as v8 from"v8";import*as os from"os";const NS_PER_SECOND=1e9,MS_PER_SECOND=1e3;function collectMemory(){const e=process.memoryUsage();return[{name:"process_resident_memory_bytes",type:"gauge",help:"Resident set size in bytes.",value:e.rss},{name:"nodejs_external_memory_bytes",type:"gauge",help:"Memory used by C++ objects bound to JavaScript, in bytes.",value:e.external},{name:"nodejs_array_buffers_bytes",type:"gauge",help:"Memory allocated for ArrayBuffers and SharedArrayBuffers, in bytes.",value:e.arrayBuffers}]}let prevCpuUsage=null;function collectCpu(){var e,t;const o=os.cpus();let l=0;if(prevCpuUsage&&prevCpuUsage.length===o.length){let e=0,t=0;for(let l=0;l<o.length;l++){const s=prevCpuUsage[l].times,a=o[l].times,n=s.user+s.nice+s.sys+s.idle+s.irq;e+=a.user+a.nice+a.sys+a.idle+a.irq-n,t+=a.idle-s.idle}l=e>0?1-t/e:0}return prevCpuUsage=o,[{name:"process_cpu_usage_ratio",type:"gauge",help:"Share of CPU time spent non-idle since the previous collection, 0 to 1.",value:l},{name:"nodejs_cpu_count",type:"gauge",help:"Number of logical CPUs.",value:o.length},{name:"nodejs_cpu_info",type:"gauge",help:"CPU model, always 1.",labels:{model:null!==(t=null===(e=o[0])||void 0===e?void 0:e.model)&&void 0!==t?t:"unknown"},value:1}]}function collectHeap(){const e=v8.getHeapStatistics();return[{name:"nodejs_heap_size_total_bytes",type:"gauge",help:"Total V8 heap size in bytes.",value:e.total_heap_size},{name:"nodejs_heap_size_used_bytes",type:"gauge",help:"Used V8 heap size in bytes.",value:e.used_heap_size},{name:"nodejs_heap_size_limit_bytes",type:"gauge",help:"Ceiling V8 will grow the heap to, in bytes.",value:e.heap_size_limit},{name:"nodejs_malloced_memory_bytes",type:"gauge",help:"Memory malloc'd by V8, in bytes.",value:e.malloced_memory},{name:"nodejs_native_contexts",type:"gauge",help:"Live top-level contexts. A number that only grows indicates a leak.",value:e.number_of_native_contexts},{name:"nodejs_detached_contexts",type:"gauge",help:"Contexts detached but not yet garbage collected.",value:e.number_of_detached_contexts}]}function collectHandles(){var e,t,o,l,s,a;const n=null!==(t=null===(e=process._getActiveHandles)||void 0===e?void 0:e.call(process))&&void 0!==t?t:[],r=null!==(l=null===(o=process._getActiveRequests)||void 0===o?void 0:o.call(process))&&void 0!==l?l:[];let c=0,u=0;for(const e of n){const t=null!==(a=null===(s=null==e?void 0:e.constructor)||void 0===s?void 0:s.name)&&void 0!==a?a:"";"Timeout"===t||"Timer"===t||"Immediate"===t?c++:"Socket"!==t&&"TCP"!==t&&"TLSSocket"!==t||u++}return[{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"timer"},value:c},{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"socket"},value:u},{name:"nodejs_active_handles",type:"gauge",help:"Active libuv handles by kind.",labels:{kind:"other"},value:n.length-c-u},{name:"nodejs_active_requests_total",type:"gauge",help:"Active libuv requests.",value:r.length}]}const TOP_MODULE_GROUPS=20;function collectModules(){var _a;try{const cache=eval("typeof require !== 'undefined' && require.cache")||{},keys=Object.keys(cache),groups=new Map;for(const e of keys){const t=e.match(/node_modules\/([^/]+)/),o=t?`node_modules/${t[1]}`:e.replace(process.cwd(),".");groups.set(o,(null!==(_a=groups.get(o))&&void 0!==_a?_a:0)+1)}const top=Array.from(groups.entries()).sort((e,t)=>t[1]-e[1]).slice(0,TOP_MODULE_GROUPS);return[{name:"nodejs_module_cache_entries",type:"gauge",help:"Entries in the CommonJS module cache.",value:keys.length},...top.map(([e,t])=>({name:"nodejs_module_cache_entries_by_group",type:"gauge",help:`Module cache entries per group, top ${TOP_MODULE_GROUPS}.`,labels:{group:e},value:t}))]}catch(e){return[{name:"nodejs_module_cache_entries",type:"gauge",help:"Entries in the CommonJS module cache.",value:0}]}}const histogram=monitorEventLoopDelay({resolution:10});function collectEventLoop(){const e=0===histogram.count,t=t=>e||!Number.isFinite(t)?0:t/NS_PER_SECOND,o=[{name:"nodejs_eventloop_lag_mean_seconds",type:"gauge",help:"Mean event loop lag over the last interval.",value:t(histogram.mean)},{name:"nodejs_eventloop_lag_min_seconds",type:"gauge",help:"Minimum event loop lag over the last interval.",value:t(histogram.min)},{name:"nodejs_eventloop_lag_max_seconds",type:"gauge",help:"Maximum event loop lag over the last interval.",value:t(histogram.max)},{name:"nodejs_eventloop_lag_p99_seconds",type:"gauge",help:"99th percentile event loop lag over the last interval.",value:t(histogram.percentile(99))}];return histogram.reset(),o}histogram.enable();const LATENCY_BUCKETS=[.005,.01,.025,.05,.1,.25,.5,1,2.5,5,10];let httpTotal=0,httpDurationSum=0;const httpBuckets=new Array(LATENCY_BUCKETS.length+1).fill(0);function recordHttpRequest(e){const t=e/MS_PER_SECOND;httpTotal++,httpDurationSum+=t;for(let e=0;e<LATENCY_BUCKETS.length;e++)t<=LATENCY_BUCKETS[e]&&httpBuckets[e]++;httpBuckets[LATENCY_BUCKETS.length]++}function collectHttp(){const e=LATENCY_BUCKETS.map((e,t)=>({le:e,count:httpBuckets[t]}));return e.push({le:1/0,count:httpBuckets[LATENCY_BUCKETS.length]}),[{name:"http_requests_total",type:"counter",help:"Requests recorded since the process started.",value:httpTotal},{name:"http_request_duration_seconds",type:"histogram",help:"Request duration in seconds.",buckets:e,sum:httpDurationSum,count:httpTotal}]}let dbChecker=null;function setDbChecker(e){dbChecker=e}function collectDbPool(){return[{name:"db_pool_connected",type:"gauge",help:"1 when the database pool reports a connection, 0 otherwise.",value:dbChecker&&dbChecker()?1:0}]}function collectLogs(e){const t=e.counts(),o="Log entries written since the process started, by level.";return[{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"error"},value:t.errors},{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"warn"},value:t.warns},{name:"nodejs_log_entries_total",type:"counter",help:o,labels:{level:"other"},value:Math.max(0,t.total-t.errors-t.warns)}]}function collectSystem(){const[e,t,o]=os.loadavg(),l="System load average.";return[{name:"nodejs_version_info",type:"gauge",help:"Node.js version and platform, always 1.",labels:{version:process.version,platform:os.platform(),arch:os.arch()},value:1},{name:"system_memory_total_bytes",type:"gauge",help:"Total system memory in bytes.",value:os.totalmem()},{name:"system_memory_free_bytes",type:"gauge",help:"Free system memory in bytes.",value:os.freemem()},{name:"process_uptime_seconds",type:"gauge",help:"Seconds since the process started.",value:process.uptime()},{name:"system_load_average",type:"gauge",help:l,labels:{period:"1m"},value:e},{name:"system_load_average",type:"gauge",help:l,labels:{period:"5m"},value:t},{name:"system_load_average",type:"gauge",help:l,labels:{period:"15m"},value:o}]}function collectMetrics(e){return[...collectMemory(),...collectCpu(),...collectHeap(),...collectHandles(),...collectModules(),...collectEventLoop(),...collectHttp(),...collectDbPool(),...collectLogs(e),...collectSystem()]}export{collectMetrics,recordHttpRequest,setDbChecker};

package/dist/syhemo/exposition.d.ts

@@ -0,0 +1,15 @@
+import type { Metric } from "./types";
+/**
+ * Renders metrics as the Prometheus text exposition format.
+ *
+ * Serve the result verbatim with `CONTENT_TYPE`; nothing else is required to
+ * be scrapeable.
+ */
+/** What a `/metrics` response must declare. */
+export declare const CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/**
+ * `# HELP` and `# TYPE` are declared once per metric name, even when several
+ * series share it under different labels — repeating them makes the scrape
+ * fail with a duplicate-metadata error.
+ */
+export declare function render(metrics: Metric[]): string;

package/dist/syhemo/exposition.js

@@ -0,0 +1 @@
+"use strict";function e(e,n){const t=Object.assign(Object.assign({},e),n),r=Object.keys(t);if(0===r.length)return"";return`{${r.map(e=>{return`${e}="${n=t[e],n.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\n/g,"\\n")}"`;var n}).join(",")}}`}function n(e){return e===1/0?"+Inf":e===-1/0?"-Inf":Number.isNaN(e)?"NaN":String(e)}function t(t){return[`${t.name}${e(t.labels)} ${n(t.value)}`]}function r(t){const r=t.buckets.map(r=>`${t.name}_bucket${e(t.labels,{le:n(r.le)})} ${n(r.count)}`);return r.push(`${t.name}_sum${e(t.labels)} ${n(t.sum)}`),r.push(`${t.name}_count${e(t.labels)} ${n(t.count)}`),r}exports.CONTENT_TYPE="text/plain; version=0.0.4; charset=utf-8",exports.render=function(e){const n=[],s=new Set;for(const a of e)s.has(a.name)||(s.add(a.name),n.push(`# HELP ${a.name} ${a.help.replace(/\n/g," ")}`),n.push(`# TYPE ${a.name} ${a.type}`)),n.push(..."histogram"===a.type?r(a):t(a));return n.length?`${n.join("\n")}\n`:""};

package/dist/syhemo/exposition.mjs

@@ -0,0 +1 @@
+const n="text/plain; version=0.0.4; charset=utf-8";function e(n,e){const t=Object.assign(Object.assign({},n),e),a=Object.keys(t);if(0===a.length)return"";return`{${a.map(n=>{return`${n}="${e=t[n],e.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\n/g,"\\n")}"`;var e}).join(",")}}`}function t(n){return n===1/0?"+Inf":n===-1/0?"-Inf":Number.isNaN(n)?"NaN":String(n)}function a(n){return[`${n.name}${e(n.labels)} ${t(n.value)}`]}function s(n){const a=n.buckets.map(a=>`${n.name}_bucket${e(n.labels,{le:t(a.le)})} ${t(a.count)}`);return a.push(`${n.name}_sum${e(n.labels)} ${t(n.sum)}`),a.push(`${n.name}_count${e(n.labels)} ${t(n.count)}`),a}function u(n){const e=[],t=new Set;for(const u of n)t.has(u.name)||(t.add(u.name),e.push(`# HELP ${u.name} ${u.help.replace(/\n/g," ")}`),e.push(`# TYPE ${u.name} ${u.type}`)),e.push(..."histogram"===u.type?s(u):a(u));return e.length?`${e.join("\n")}\n`:""}export{n as CONTENT_TYPE,u as render};

package/dist/syhemo/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Syhemo: in-process runtime monitoring.
+ *
+ * Node-only, and not re-exported from the package index — reach it by
+ * subpath: `import { Syhemo } from "@ecosy/core/syhemo"`.
+ *
+ * Metrics follow the Prometheus model, so exposing them is a two-line route
+ * with no client library involved:
+ *
+ * ```ts
+ * export function GET() {
+ *   return new Response(monitor.metrics(), {
+ *     headers: { "Content-Type": CONTENT_TYPE },
+ *   });
+ * }
+ * ```
+ *
+ * Collection runs on this class's own timer, never on a scrape, which is what
+ * makes that route safe to call from more than one scraper: reading never
+ * mutates a counter.
+ */
+import { Subscriber } from "../subscriber";
+import type { Metric, SyhemoDeps, SyhemoOptions, SyhemoState } from "./types";
+export * from "./types";
+export { recordHttpRequest } from "./collectors";
+export { render, CONTENT_TYPE } from "./exposition";
+declare const syhemoEvents: {
+    readonly metrics: {
+        readonly snapshot: "syhemo:metrics:snapshot";
+    };
+};
+type SyhemoEvents = typeof syhemoEvents;
+export declare class Syhemo extends Subscriber<SyhemoState, SyhemoEvents> {
+    private timer;
+    private readonly logger;
+    private readonly source;
+    constructor(deps?: SyhemoDeps);
+    start(options?: SyhemoOptions): void;
+    stop(): void;
+    /** The most recent collection, or an empty list before the first one. */
+    getMetrics(): Metric[];
+    /**
+     * The most recent collection in Prometheus text exposition format.
+     *
+     * Serve it with `CONTENT_TYPE`. Returns an empty string before the first
+     * collection, which a scraper reads as "no metrics" rather than an error.
+     */
+    metrics(): string;
+    private collect;
+}

package/dist/syhemo/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("../subscriber.js"),t=require("../utilities/freeze.js"),s=require("./logger.js"),r=require("./collectors.js"),i=require("./exposition.js");const o=t.freeze({metrics:{snapshot:"syhemo:metrics:snapshot"}});class l extends e.Subscriber{constructor(e={}){var t,r;super({current:null,snapshots:[],logs:[],started:!1},o),this.timer=null,this.logger=null!==(t=e.logger)&&void 0!==t?t:new s.BufferedLogger("Syhemo"),this.source=null!==(r=e.source)&&void 0!==r?r:s.BufferedLogger}start(e={}){if(this.getState().started)return;const{interval:t=5e3,db:s}=e;s&&r.setDbChecker(s),this.setState({started:!0}),this.collect(),this.timer=setInterval(()=>this.collect(),t),this.logger.log(`Started (interval: ${t}ms)`)}stop(){this.timer&&(clearInterval(this.timer),this.timer=null),this.setState({started:!1}),this.logger.log("Stopped")}getMetrics(){var e,t;return null!==(t=null===(e=this.getState().current)||void 0===e?void 0:e.metrics)&&void 0!==t?t:[]}metrics(){return i.render(this.getMetrics())}collect(){try{const e={timestamp:Date.now(),metrics:r.collectMetrics(this.source)},t=this.getState().snapshots,s=t.length>=60?[...t.slice(1),e]:[...t,e];this.setState({current:e,snapshots:s,logs:this.source.getLogs()}),this.dispatch(o.metrics.snapshot,e)}catch(e){this.logger.error(`Collection failed: ${e}`)}}}exports.recordHttpRequest=r.recordHttpRequest,exports.CONTENT_TYPE=i.CONTENT_TYPE,exports.render=i.render,exports.Syhemo=l;

package/dist/syhemo/index.mjs

@@ -0,0 +1 @@
+import{Subscriber as t}from"../subscriber.mjs";import{freeze as s}from"../utilities/freeze.mjs";import{BufferedLogger as e}from"./logger.mjs";import{collectMetrics as r,setDbChecker as o}from"./collectors.mjs";export{recordHttpRequest}from"./collectors.mjs";import{render as i}from"./exposition.mjs";export{CONTENT_TYPE}from"./exposition.mjs";const l=s({metrics:{snapshot:"syhemo:metrics:snapshot"}});class c extends t{constructor(t={}){var s,r;super({current:null,snapshots:[],logs:[],started:!1},l),this.timer=null,this.logger=null!==(s=t.logger)&&void 0!==s?s:new e("Syhemo"),this.source=null!==(r=t.source)&&void 0!==r?r:e}start(t={}){if(this.getState().started)return;const{interval:s=5e3,db:e}=t;e&&o(e),this.setState({started:!0}),this.collect(),this.timer=setInterval(()=>this.collect(),s),this.logger.log(`Started (interval: ${s}ms)`)}stop(){this.timer&&(clearInterval(this.timer),this.timer=null),this.setState({started:!1}),this.logger.log("Stopped")}getMetrics(){var t,s;return null!==(s=null===(t=this.getState().current)||void 0===t?void 0:t.metrics)&&void 0!==s?s:[]}metrics(){return i(this.getMetrics())}collect(){try{const t={timestamp:Date.now(),metrics:r(this.source)},s=this.getState().snapshots,e=s.length>=60?[...s.slice(1),t]:[...s,t];this.setState({current:t,snapshots:e,logs:this.source.getLogs()}),this.dispatch(l.metrics.snapshot,t)}catch(t){this.logger.error(`Collection failed: ${t}`)}}}export{c as Syhemo,i as render};

package/dist/{logger.d.ts → syhemo/logger.d.ts}

@@ -12,24 +12,32 @@ export interface LogEntry {
     message: string;
 }
 /**
- * Isomorphic logger with color-coded output.
+ * Syhemo's built-in logging stack: colour-coded output plus the shared buffer
+ * and counters the monitor reads.
  *
- * - **Server (Node.js)**: Uses ANSI escape codes for terminal coloring.
- * - **Browser**: Uses `%c` CSS formatting for DevTools console.
+ * This is NOT a general-purpose logger, and it is not re-exported from the
+ * package index — reach for `@ecosy/logger` for formatters, deliveries and
+ * telemetry standards. What lives here exists so that {@link Syhemo} works out
+ * of the box: it is one concrete implementation of the `SyhemoLogger` and
+ * `SyhemoLogSource` ports, and Syhemo accepts any other.
  *
- * All log entries are buffered in a shared `globalThis` store so that
- * {@link Syhemo} can collect them for monitoring.
+ * An app that wants its own logs to appear in monitoring snapshots has to
+ * write them through something that fills the same buffer — either this class,
+ * or its own implementation of `SyhemoLogSource` handed to Syhemo.
+ *
+ * - **Server (Node.js)**: ANSI escape codes for terminal colour.
+ * - **Browser**: `%c` CSS formatting for DevTools.
  *
  * @example
  * ```ts
- * const logger = new Logger("MyModule");
+ * const logger = new BufferedLogger("MyModule");
  * logger.log("Server started on port 3000");
  * logger.warn("Deprecated API used");
  * logger.error("Connection failed", error);
  * logger.debug("Payload:", data);
  * ```
  */
-export declare class Logger {
+export declare class BufferedLogger {
     private readonly context;
     /**
      * @param context - Label shown in log output, e.g. `[MyModule]`.
@@ -51,14 +59,18 @@ export declare class Logger {
     verbose(message: string, ...args: unknown[]): void;
     /**
      * Returns a shallow copy of all buffered log entries (non-destructive).
-     * Used by {@link Syhemo} to collect logs for monitoring snapshots.
+     * Satisfies the `getLogs` half of Syhemo's log source port.
      */
     static getLogs(): LogEntry[];
     /**
-     * Returns the current error, warn, and total log counts, then resets
-     * the counters to zero. Used by {@link Syhemo} for per-interval log rate tracking.
+     * Running totals since the process started.
+     *
+     * Non-destructive on purpose: these become Prometheus counters, and a
+     * counter that resets when it is read cannot be shared by two consumers and
+     * cannot produce a correct rate. The scraper takes the difference between
+     * two reads; that is its job, not this one's.
      */
-    static drainCounts(): {
+    static counts(): {
         errors: number;
         warns: number;
         total: number;

package/dist/syhemo/logger.js

@@ -0,0 +1 @@
+"use strict";const o=()=>"undefined"==typeof window,t="",r="",e="",n="",s={LOG:"color:#22c55e;font-weight:bold",WARN:"color:#eab308;font-weight:bold",ERROR:"color:#ef4444;font-weight:bold",DEBUG:"color:#a855f7;font-weight:bold",VERBOSE:"color:#06b6d4;font-weight:bold"},c="color:inherit;font-weight:normal",i={LOG:"color:#22c55e",WARN:"color:#eab308",ERROR:"color:#ef4444",DEBUG:"color:#a855f7",VERBOSE:"color:#06b6d4"};function a(){return(new Date).toLocaleString("en-US",{month:"2-digit",day:"2-digit",year:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit",hour12:!0})}const f={LOG:"",WARN:e,ERROR:"",DEBUG:"",VERBOSE:""},l=Symbol.for("@ecosy:logger"),m=globalThis;m[l]||(m[l]={buffer:[],errors:0,warns:0,total:0});const R=m[l];exports.BufferedLogger=class{constructor(o="@ecosy"){this.context=o}format(t,r,...e){const n="ERROR"===t?console.error:"WARN"===t?console.warn:console.log;R.buffer.push({timestamp:Date.now(),level:t,context:this.context,message:r}),R.buffer.length>200&&R.buffer.shift(),R.total++,"ERROR"===t&&R.errors++,"WARN"===t&&R.warns++,o()?this.formatServer(n,t,r,...e):this.formatBrowser(n,t,r,...e)}formatServer(s,c,i,...l){const m=f[c],R=`${n}${a()}${t}`;s(`${`${m}${r}${c.padEnd(7)}${t}`} ${`${e}${o()&&"undefined"!=typeof process?process.pid:0}${t}`}  - ${R}     ${`${e}[${this.context}]${t}`} ${`${m}${i}${t}`}`,...l)}formatBrowser(o,t,r,...e){o(`%c${t.padEnd(7)}%c  - %c${a()}%c     %c[${this.context}]%c %c${r}`,s[t],c,"color:#9ca3af;font-weight:normal",c,"color:#eab308;font-weight:normal",c,i[t],...e)}log(o,...t){this.format("LOG",o,...t)}warn(o,...t){this.format("WARN",o,...t)}error(o,...t){this.format("ERROR",o,...t)}debug(o,...t){this.format("DEBUG",o,...t)}verbose(o,...t){this.format("VERBOSE",o,...t)}static getLogs(){return[...R.buffer]}static counts(){return{errors:R.errors,warns:R.warns,total:R.total}}};

package/dist/{logger.mjs → syhemo/logger.mjs}

@@ -1 +1 @@
-const o=()=>"undefined"==typeof window,t="",r="",e="",n="",s={LOG:"color:#22c55e;font-weight:bold",WARN:"color:#eab308;font-weight:bold",ERROR:"color:#ef4444;font-weight:bold",DEBUG:"color:#a855f7;font-weight:bold",VERBOSE:"color:#06b6d4;font-weight:bold"},c="color:inherit;font-weight:normal",a={LOG:"color:#22c55e",WARN:"color:#eab308",ERROR:"color:#ef4444",DEBUG:"color:#a855f7",VERBOSE:"color:#06b6d4"};function i(){return(new Date).toLocaleString("en-US",{month:"2-digit",day:"2-digit",year:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit",hour12:!0})}const f={LOG:"",WARN:e,ERROR:"",DEBUG:"",VERBOSE:""},l=Symbol.for("@ecosy:logger"),m=globalThis;m[l]||(m[l]={buffer:[],errors:0,warns:0,total:0});const R=m[l];class h{constructor(o="@ecosy"){this.context=o}format(t,r,...e){const n="ERROR"===t?console.error:"WARN"===t?console.warn:console.log;R.buffer.push({timestamp:Date.now(),level:t,context:this.context,message:r}),R.buffer.length>200&&R.buffer.shift(),R.total++,"ERROR"===t&&R.errors++,"WARN"===t&&R.warns++,o()?this.formatServer(n,t,r,...e):this.formatBrowser(n,t,r,...e)}formatServer(s,c,a,...l){const m=f[c],R=`${n}${i()}${t}`;s(`${`${m}${r}${c.padEnd(7)}${t}`} ${`${e}${o()&&"undefined"!=typeof process?process.pid:0}${t}`}  - ${R}     ${`${e}[${this.context}]${t}`} ${`${m}${a}${t}`}`,...l)}formatBrowser(o,t,r,...e){o(`%c${t.padEnd(7)}%c  - %c${i()}%c     %c[${this.context}]%c %c${r}`,s[t],c,"color:#9ca3af;font-weight:normal",c,"color:#eab308;font-weight:normal",c,a[t],...e)}log(o,...t){this.format("LOG",o,...t)}warn(o,...t){this.format("WARN",o,...t)}error(o,...t){this.format("ERROR",o,...t)}debug(o,...t){this.format("DEBUG",o,...t)}verbose(o,...t){this.format("VERBOSE",o,...t)}static getLogs(){return[...R.buffer]}static drainCounts(){const o={errors:R.errors,warns:R.warns,total:R.total};return R.errors=0,R.warns=0,R.total=0,o}}export{h as Logger};
+const o=()=>"undefined"==typeof window,t="",r="",e="",n="",c={LOG:"color:#22c55e;font-weight:bold",WARN:"color:#eab308;font-weight:bold",ERROR:"color:#ef4444;font-weight:bold",DEBUG:"color:#a855f7;font-weight:bold",VERBOSE:"color:#06b6d4;font-weight:bold"},s="color:inherit;font-weight:normal",i={LOG:"color:#22c55e",WARN:"color:#eab308",ERROR:"color:#ef4444",DEBUG:"color:#a855f7",VERBOSE:"color:#06b6d4"};function a(){return(new Date).toLocaleString("en-US",{month:"2-digit",day:"2-digit",year:"numeric",hour:"2-digit",minute:"2-digit",second:"2-digit",hour12:!0})}const f={LOG:"",WARN:e,ERROR:"",DEBUG:"",VERBOSE:""},l=Symbol.for("@ecosy:logger"),m=globalThis;m[l]||(m[l]={buffer:[],errors:0,warns:0,total:0});const R=m[l];class h{constructor(o="@ecosy"){this.context=o}format(t,r,...e){const n="ERROR"===t?console.error:"WARN"===t?console.warn:console.log;R.buffer.push({timestamp:Date.now(),level:t,context:this.context,message:r}),R.buffer.length>200&&R.buffer.shift(),R.total++,"ERROR"===t&&R.errors++,"WARN"===t&&R.warns++,o()?this.formatServer(n,t,r,...e):this.formatBrowser(n,t,r,...e)}formatServer(c,s,i,...l){const m=f[s],R=`${n}${a()}${t}`;c(`${`${m}${r}${s.padEnd(7)}${t}`} ${`${e}${o()&&"undefined"!=typeof process?process.pid:0}${t}`}  - ${R}     ${`${e}[${this.context}]${t}`} ${`${m}${i}${t}`}`,...l)}formatBrowser(o,t,r,...e){o(`%c${t.padEnd(7)}%c  - %c${a()}%c     %c[${this.context}]%c %c${r}`,c[t],s,"color:#9ca3af;font-weight:normal",s,"color:#eab308;font-weight:normal",s,i[t],...e)}log(o,...t){this.format("LOG",o,...t)}warn(o,...t){this.format("WARN",o,...t)}error(o,...t){this.format("ERROR",o,...t)}debug(o,...t){this.format("DEBUG",o,...t)}verbose(o,...t){this.format("VERBOSE",o,...t)}static getLogs(){return[...R.buffer]}static counts(){return{errors:R.errors,warns:R.warns,total:R.total}}}export{h as BufferedLogger};

package/dist/syhemo/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Every shape Syhemo produces or consumes.
+ *
+ * The metric model below follows Prometheus, so a project that wants a
+ * `/metrics` endpoint only has to return what Syhemo already produces — no
+ * client library, no registry, no push gateway. That constrains three things
+ * which are easy to get wrong and expensive to fix later:
+ *
+ *  - **Base units.** Bytes, seconds, and ratios between 0 and 1. Never MB, ms
+ *    or percentages: a query that has to know which unit a metric used is a
+ *    query that will eventually be wrong.
+ *  - **Counters are monotonic.** `counter` *means* never-decreasing; a scraper
+ *    computes rates from the difference between two scrapes. A value that
+ *    resets itself is a gauge wearing a counter's name, and the dashboards it
+ *    produces look plausible while being wrong.
+ *  - **Full precision.** Values are not rounded here. Rounding is a display
+ *    decision, and doing it at the source cannot be undone.
+ */
+import type { LogEntry, LogLevel } from "./logger";
+export type { LogEntry, LogLevel };
+/**
+ * `counter` only ever grows. `gauge` moves in both directions. `histogram`
+ * carries cumulative buckets plus a sum and a count.
+ *
+ * Summaries are deliberately absent: their quantiles cannot be aggregated
+ * across instances, which is the whole reason histograms exist.
+ */
+export type MetricType = "counter" | "gauge" | "histogram";
+export type MetricLabels = Record<string, string>;
+/** One cumulative bucket: how many observations were `<= le`. */
+export interface HistogramBucket {
+    /** Upper bound, inclusive. `Infinity` renders as `+Inf`. */
+    le: number;
+    count: number;
+}
+interface MetricBase {
+    /** `<namespace>_<subsystem>_<name>_<unit>`, e.g. `process_resident_memory_bytes`. */
+    name: string;
+    help: string;
+    labels?: MetricLabels;
+}
+export interface ScalarMetric extends MetricBase {
+    type: "counter" | "gauge";
+    value: number;
+}
+export interface HistogramMetric extends MetricBase {
+    type: "histogram";
+    /** Cumulative: each bucket counts everything at or below its bound. */
+    buckets: HistogramBucket[];
+    sum: number;
+    count: number;
+}
+export type Metric = ScalarMetric | HistogramMetric;
+/** One collection pass. */
+export interface MetricsSnapshot {
+    /** Unix milliseconds. */
+    timestamp: number;
+    metrics: Metric[];
+}
+export interface SyhemoState {
+    current: MetricsSnapshot | null;
+    snapshots: MetricsSnapshot[];
+    logs: LogEntry[];
+    started: boolean;
+}
+/** Monotonic log totals since the process started. */
+export interface LogCounts {
+    errors: number;
+    warns: number;
+    total: number;
+}
+/**
+ * Where Syhemo writes its own diagnostics.
+ *
+ * Structurally an `ILogger`, so `@ecosy/logger` — or a bare `console` — is
+ * already one. Declared here rather than imported because it is the port the
+ * monitor needs, which is what keeps this package free of any dependency on a
+ * logging library.
+ */
+export interface SyhemoLogger {
+    log(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Where Syhemo reads log activity from.
+ *
+ * A logging library does not normally provide this — writing logs and being
+ * able to count them are different jobs — which is why it is a separate port.
+ * `BufferedLogger` implements both; pairing `@ecosy/logger` with monitoring
+ * means giving it a delivery that fills something shaped like this.
+ */
+export interface SyhemoLogSource {
+    /** Recent entries. Non-destructive. */
+    getLogs(): LogEntry[];
+    /**
+     * Running totals since the process started.
+     *
+     * Must be monotonic and non-destructive: these become counters, and a
+     * counter that resets when it is read cannot be shared by two consumers and
+     * cannot produce a correct rate.
+     */
+    counts(): LogCounts;
+}
+export interface SyhemoOptions {
+    interval?: number;
+    db?: () => boolean;
+}
+export interface SyhemoDeps {
+    /** Defaults to the built-in `BufferedLogger`. */
+    logger?: SyhemoLogger;
+    /** Defaults to the built-in buffer behind `BufferedLogger`. */
+    source?: SyhemoLogSource;
+}

package/dist/utilities/index.d.ts

@@ -10,4 +10,6 @@ export { isLiteralObject, isComplexObject, isObject, isObjectable, hasOwnPropert
 export { merge } from "./merge";
 export { isFormData, objectToFormData } from "./formdata";
 export { MIME_REGEX, sanitizeMime } from "./sanitize-mime";
+export { searchify, type SearchPosition, type SearchResult } from "./searchify";
+export { slugify, DEFAULT_TRANSFORMER, type SlugifyOptions } from "./slugify";
 export { toString, ucfirst, pascalToKebab } from "./string";