@demicodes/utils 0.13.0 → 0.14.1

package/dist/index.d.mts

@@ -90,6 +90,23 @@ declare function base64ToBytes(base64: string): Uint8Array;
 declare function clamp(value: number, min: number, max: number): number;
 /** Strips trailing slashes from a base URL so paths can be appended consistently. */
 declare function normalizeBaseUrl(baseUrl: string): string;
+/**
+ * Slices the first `maxChars` UTF-16 units of `text` without splitting a
+ * surrogate pair: a cut that would leave a trailing lone high surrogate moves
+ * back one unit instead.
+ */
+declare function sliceHead(text: string, maxChars: number): string;
+/**
+ * Slices the last `maxChars` UTF-16 units of `text` without splitting a
+ * surrogate pair: a cut that would leave a leading lone low surrogate moves
+ * forward one unit instead.
+ */
+declare function sliceTail(text: string, maxChars: number): string;
+/**
+ * Replaces lone UTF-16 surrogates with U+FFFD so the string is well-formed
+ * Unicode and can be serialized into any wire payload.
+ */
+declare function toWellFormedText(text: string): string;
 /** Truncates `text` to at most `maxChars` characters, appending `ellipsis` when shortened. */
 declare function truncate(text: string, maxChars: number, ellipsis?: string): string;
 /** Returns the last `maxChars` characters of `text`. */
@@ -137,4 +154,4 @@ declare function isAbsolutePath(path: string): boolean;
 /** Generates a random UUID. */
 declare function createId(): string;
 //#endregion
-export { AbortError, Deferred, PortableJsonValue, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, stringOrNull, stringifyPortableJson, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };
+export { AbortError, Deferred, PortableJsonValue, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, sliceHead, sliceTail, stringOrNull, stringifyPortableJson, tail, throwIfAborted, toWellFormedText, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };

package/dist/index.mjs

@@ -248,15 +248,46 @@ function clamp(value, min, max) {
 function normalizeBaseUrl(baseUrl) {
 	return baseUrl.replace(/\/+$/, "");
 }
+/**
+* Slices the first `maxChars` UTF-16 units of `text` without splitting a
+* surrogate pair: a cut that would leave a trailing lone high surrogate moves
+* back one unit instead.
+*/
+function sliceHead(text, maxChars) {
+	if (maxChars <= 0) return "";
+	if (text.length <= maxChars) return text;
+	const cut = text.charCodeAt(maxChars - 1);
+	return text.slice(0, cut >= 55296 && cut <= 56319 ? maxChars - 1 : maxChars);
+}
+/**
+* Slices the last `maxChars` UTF-16 units of `text` without splitting a
+* surrogate pair: a cut that would leave a leading lone low surrogate moves
+* forward one unit instead.
+*/
+function sliceTail(text, maxChars) {
+	if (maxChars <= 0) return "";
+	if (text.length <= maxChars) return text;
+	const start = text.length - maxChars;
+	const cut = text.charCodeAt(start);
+	return text.slice(cut >= 56320 && cut <= 57343 ? start + 1 : start);
+}
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+* Replaces lone UTF-16 surrogates with U+FFFD so the string is well-formed
+* Unicode and can be serialized into any wire payload.
+*/
+function toWellFormedText(text) {
+	return text.replace(LONE_SURROGATE, "�");
+}
 /** Truncates `text` to at most `maxChars` characters, appending `ellipsis` when shortened. */
 function truncate(text, maxChars, ellipsis = "…") {
 	if (text.length <= maxChars) return text;
-	if (maxChars <= ellipsis.length) return text.slice(0, Math.max(0, maxChars));
-	return text.slice(0, maxChars - ellipsis.length) + ellipsis;
+	if (maxChars <= ellipsis.length) return sliceHead(text, maxChars);
+	return sliceHead(text, maxChars - ellipsis.length) + ellipsis;
 }
 /** Returns the last `maxChars` characters of `text`. */
 function tail(text, maxChars) {
-	return text.length <= maxChars ? text : text.slice(text.length - maxChars);
+	return sliceTail(text, maxChars);
 }
 /** A short, stable hex hash of a string (32-bit FNV-1a). Not cryptographic. */
 function shortHash(value) {
@@ -389,4 +420,4 @@ function createId() {
 	return globalThis.crypto.randomUUID();
 }
 //#endregion
-export { AbortError, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, stringOrNull, stringifyPortableJson, tail, throwIfAborted, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };
+export { AbortError, abortable, asError, asRecord, asString, base64ToBytes, bytesToBase64, clamp, concatBytes, createId, decodeLatin1, decodeUtf8, decodeUtf8Strict, deferred, delay, dirnamePath, encodeLatin1, encodeUtf8, errorCode, errorMessage, isAbortError, isAbsolutePath, isFileNotFoundError, isRecord, nonEmptyString, noop, normalizeBaseUrl, normalizePath, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, parsePortableJson, safeJsonStringify, shortHash, sliceHead, sliceTail, stringOrNull, stringifyPortableJson, tail, throwIfAborted, toWellFormedText, truncate, utf8Bytes, utf8Slice, waitFor, withTimeout };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/utils",
   "description": "Shared zero-dependency utilities for Demi (type guards, errors, async, bytes, strings, paths, JSON).",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.mjs",