@duplojs/utils 1.4.36 → 1.4.38

package/dist/common/asserts.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var errorKindNamespace = require('./errorKindNamespace.cjs');
+var kind = require('./kind.cjs');
+
+class AssertsError extends kind.kindHeritage("asserts-error", errorKindNamespace.createErrorKind("asserts-error"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Asserts Error."]);
+        this.value = value;
+    }
+}
+/**
+ * {@include common/asserts/index.md}
+ */
+function asserts(input, predicate) {
+    if (!predicate(input)) {
+        throw new AssertsError(input);
+    }
+}
+
+exports.AssertsError = AssertsError;
+exports.asserts = asserts;

package/dist/common/asserts.d.ts

@@ -0,0 +1,38 @@
+declare const AssertsError_base: new (params: {
+    "@DuplojsUtilsError/asserts-error"?: unknown;
+}, parentParams: [message?: string | undefined, options?: ErrorOptions | undefined]) => Error & import("./kind").Kind<import("./kind").KindDefinition<"asserts-error", unknown>, unknown> & import("./kind").Kind<import("./kind").KindDefinition<"@DuplojsUtilsError/asserts-error", unknown>, unknown>;
+export declare class AssertsError extends AssertsError_base {
+    value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * The asserts() function throws when a predicate fails and narrows the input type when it passes.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asserts(input, predicate)` → narrows the input type or throws
+ * 
+ * It throws an `AssertsError` with the failing input value.
+ * 
+ * ```ts
+ * const input: string | number = "demo";
+ * asserts(input, isType("string"));
+ * 
+ * const payload: { id?: number } = { id: 1 };
+ * asserts(payload.id, isType("undefined"));
+ * 
+ * try {
+ * 	asserts(42 as string | number, isType("string"));
+ * } catch (error) {
+ * 	if (error instanceof AssertsError) {
+ * 		const failedValue = error.value;
+ * 	}
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/asserts
+ * 
+ * @namespace C
+ * 
+ */
+export declare function asserts<GenericInput extends unknown, GenericPredicate extends GenericInput>(input: GenericInput, predicate: (input: GenericInput) => input is GenericPredicate): asserts input is GenericPredicate;
+export {};

package/dist/common/asserts.mjs

@@ -0,0 +1,20 @@
+import { createErrorKind } from './errorKindNamespace.mjs';
+import { kindHeritage } from './kind.mjs';
+
+class AssertsError extends kindHeritage("asserts-error", createErrorKind("asserts-error"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Asserts Error."]);
+        this.value = value;
+    }
+}
+/**
+ * {@include common/asserts/index.md}
+ */
+function asserts(input, predicate) {
+    if (!predicate(input)) {
+        throw new AssertsError(input);
+    }
+}
+
+export { AssertsError, asserts };

package/dist/common/index.d.ts

@@ -14,7 +14,7 @@
  * 
  * What you will find in this namespace:
  * - composition helpers (`pipe`, `innerPipe`, `asyncPipe`, `asyncInnerPipe`, `forward`)
- * - predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `instanceOf`)
+ * - predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `asserts`, `instanceOf`)
  * - control flow (`loop`, `asyncLoop`, `asyncRetry`, `sleep`, `memo`)
  * - promise utilities (`externalPromise`, `promiseObject`)
  * - string and value conversions (`toString`, `stringToMillisecond`, `stringToBytes`, `escapeRegExp`)
@@ -74,3 +74,4 @@ export * from "./hasSomeKinds";
 export * from "./hasKinds";
 export * from "./toCurriedPredicate";
 export * from "./pipeCall";
+export * from "./asserts";

package/dist/common/types/index.d.ts

@@ -44,3 +44,4 @@ export * from "./sortType";
 export * from "./maybeGetter";
 export * from "./falsyValue";
 export * from "./DeepReadonly";
+export * from "./json";

package/dist/common/types/json.d.ts

@@ -0,0 +1,4 @@
+import { type MaybeArray } from "./maybeArray";
+export type Json = MaybeArray<string | undefined | boolean | number | null | {
+    [key: string]: Json;
+}>;

package/dist/dataParser/parsers/nullable.d.ts

@@ -51,7 +51,7 @@ export interface DataParserNullable<GenericDefinition extends DataParserDefiniti
  * @namespace DP
  * 
  */
-export declare function nullable<GenericDataParser extends DataParser, const GenericDefinition extends Partial<Omit<DataParserDefinitionNullable<Output<GenericDataParser> | null>, "inner">> = never>(inner: GenericDataParser, definition?: GenericDefinition): DataParserNullable<MergeDefinition<DataParserDefinitionNullable, NeverCoalescing<GenericDefinition, {}> & {
+export declare function nullable<GenericDataParser extends DataParser, const GenericDefinition extends Partial<Omit<DataParserDefinitionNullable<Output<GenericDataParser>>, "inner">> = never>(inner: GenericDataParser, definition?: GenericDefinition): DataParserNullable<MergeDefinition<DataParserDefinitionNullable, NeverCoalescing<GenericDefinition, {}> & {
     inner: GenericDataParser;
 }>>;
 export declare namespace nullable {

package/dist/dataParser/parsers/optional.d.ts

@@ -51,7 +51,7 @@ export interface DataParserOptional<GenericDefinition extends DataParserDefiniti
  * @namespace DP
  * 
  */
-export declare function optional<GenericDataParser extends DataParser, const GenericDefinition extends Partial<Omit<DataParserDefinitionOptional<Output<GenericDataParser> | undefined>, "inner">> = never>(inner: GenericDataParser, definition?: GenericDefinition): DataParserOptional<MergeDefinition<DataParserDefinitionOptional, NeverCoalescing<GenericDefinition, {}> & {
+export declare function optional<GenericDataParser extends DataParser, const GenericDefinition extends Partial<Omit<DataParserDefinitionOptional<Output<GenericDataParser>>, "inner">> = never>(inner: GenericDataParser, definition?: GenericDefinition): DataParserOptional<MergeDefinition<DataParserDefinitionOptional, NeverCoalescing<GenericDefinition, {}> & {
     inner: GenericDataParser;
 }>>;
 export declare namespace optional {

package/dist/either/right/asyncPipe.d.ts

@@ -1,12 +1,12 @@
 import { type EitherRight } from "./create";
 import { type EitherLeft } from "../left";
 import { type MaybeFutureEither } from "../future/maybeFutureEither";
-import { type Future } from "../future";
+import { type EitherFutureError, type Future } from "../future";
 import { type EitherSuccess } from "./success";
 import { type AnyValue, type Unwrap } from "../../common";
 type Either = EitherRight | EitherLeft;
 export type EitherRightAsyncPipeFunction<GenericInput extends AnyValue = AnyValue, GenericOutput extends MaybeFutureEither<AnyValue> = MaybeFutureEither<AnyValue>> = (input: Awaited<GenericInput> extends infer InferredInput ? InferredInput extends Either ? Unwrap<Exclude<InferredInput, EitherLeft>> : InferredInput : never) => GenericOutput;
-export type EitherRightAsyncPipeResult<GenericPipeOutputs extends AnyValue, GenericLastPipeOutput extends AnyValue> = Extract<Awaited<GenericPipeOutputs>, EitherLeft> | (Awaited<GenericLastPipeOutput> extends infer InferredLastResult ? Exclude<InferredLastResult extends Either ? InferredLastResult : EitherSuccess<InferredLastResult>, EitherLeft> : never);
+export type EitherRightAsyncPipeResult<GenericPipeOutputs extends AnyValue, GenericLastPipeOutput extends AnyValue> = (Extract<Awaited<GenericPipeOutputs>, EitherLeft> | (Awaited<GenericLastPipeOutput> extends infer InferredLastResult ? Exclude<InferredLastResult extends Either ? InferredLastResult : EitherSuccess<InferredLastResult>, EitherLeft> : never) | (Promise<any> extends Exclude<GenericPipeOutputs, Future<any>> ? EitherFutureError : never));
 /**
  * Asynchronous version of rightPipe. Automatically handles promises, Future, and Either, and short-circuits on the first Left.
  * 

package/dist/index.cjs

@@ -60,6 +60,7 @@ var hasSomeKinds = require('./common/hasSomeKinds.cjs');
 var hasKinds = require('./common/hasKinds.cjs');
 var toCurriedPredicate = require('./common/toCurriedPredicate.cjs');
 var pipeCall = require('./common/pipeCall.cjs');
+var asserts = require('./common/asserts.cjs');
 
 
 
@@ -147,3 +148,5 @@ exports.hasSomeKinds = hasSomeKinds.hasSomeKinds;
 exports.hasKinds = hasKinds.hasKinds;
 exports.toCurriedPredicate = toCurriedPredicate.toCurriedPredicate;
 exports.pipeCall = pipeCall.pipeCall;
+exports.AssertsError = asserts.AssertsError;
+exports.asserts = asserts.asserts;

package/dist/index.mjs

@@ -82,3 +82,4 @@ export { hasSomeKinds } from './common/hasSomeKinds.mjs';
 export { hasKinds } from './common/hasKinds.mjs';
 export { toCurriedPredicate } from './common/toCurriedPredicate.mjs';
 export { pipeCall } from './common/pipeCall.mjs';
+export { AssertsError, asserts } from './common/asserts.mjs';

package/dist/metadata.json

@@ -1074,6 +1074,9 @@
             {
               "name": "isUnion.d.ts"
             },
+            {
+              "name": "json.d.ts"
+            },
             {
               "name": "lastUnionElement.d.ts"
             },
@@ -1166,6 +1169,15 @@
         {
           "name": "and.mjs"
         },
+        {
+          "name": "asserts.cjs"
+        },
+        {
+          "name": "asserts.d.ts"
+        },
+        {
+          "name": "asserts.mjs"
+        },
         {
           "name": "asyncInnerPipe.cjs"
         },
@@ -4898,6 +4910,15 @@
         {
           "name": "test.mjs"
         },
+        {
+          "name": "to.cjs"
+        },
+        {
+          "name": "to.d.ts"
+        },
+        {
+          "name": "to.mjs"
+        },
         {
           "name": "toLowerCase.cjs"
         },

package/dist/string/index.cjs

@@ -29,6 +29,7 @@ var isIn = require('./isIn.cjs');
 var length = require('./length.cjs');
 var sort = require('./sort.cjs');
 var sortCompare = require('./sortCompare.cjs');
+var to = require('./to.cjs');
 var _default = require('./at/default.cjs');
 var first = require('./at/first.cjs');
 var last = require('./at/last.cjs');
@@ -69,6 +70,7 @@ exports.isIn = isIn.isIn;
 exports.length = length.length;
 exports.sort = sort.sort;
 exports.sortCompare = sortCompare.sortCompare;
+exports.to = to.to;
 exports.at = _default.at;
 exports.first = first.first;
 exports.last = last.last;

package/dist/string/index.d.ts

@@ -18,7 +18,7 @@
  * - composition and slicing (`S.concat`, `S.slice`, `S.substring`, `S.split`)
  * - indexing (`S.at`, `S.charAt`, `S.indexOf`, `S.lastIndexOf`)
  * - padding and repeat (`S.padStart`, `S.padEnd`, `S.repeat`)
- * - misc helpers (`S.normalize`, `S.isKeyof`, `S.isIn`, `S.length`, `S.sort`, `S.sortCompare`)
+ * - misc helpers (`S.normalize`, `S.isKeyof`, `S.isIn`, `S.length`, `S.sort`, `S.sortCompare`, `S.to`)
  * 
  * @see https://utils.duplojs.dev/en/v1/api/string
  * 
@@ -57,3 +57,4 @@ export * from "./isIn";
 export * from "./length";
 export * from "./sort";
 export * from "./sortCompare";
+export * from "./to";

package/dist/string/index.mjs

@@ -27,6 +27,7 @@ export { isIn } from './isIn.mjs';
 export { length } from './length.mjs';
 export { sort } from './sort.mjs';
 export { sortCompare } from './sortCompare.mjs';
+export { to } from './to.mjs';
 export { at } from './at/default.mjs';
 export { first } from './at/first.mjs';
 export { last } from './at/last.mjs';

package/dist/string/to.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+/**
+ * {@include string/to/index.md}
+ */
+function to(value) {
+    return `${value}`;
+}
+
+exports.to = to;

package/dist/string/to.d.ts

@@ -0,0 +1,23 @@
+type Primitive = (string | boolean | null | number | undefined | bigint);
+/**
+ * Converts a primitive value to its string representation.
+ * 
+ * **Supported call styles:**
+ * - Classic: `to(value)` -> returns a string
+ * 
+ * It uses template literal conversion and preserves literal types when possible.
+ * 
+ * ```ts
+ * const fromNumber = S.to(42);
+ * const fromBoolean = S.to(false);
+ * const fromNull = S.to(null);
+ * const fromBigInt = S.to(10n);
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/to
+ * 
+ * @namespace S
+ * 
+ */
+export declare function to<GenericValue extends Primitive>(value: GenericValue): `${GenericValue}`;
+export {};

package/dist/string/to.mjs

@@ -0,0 +1,8 @@
+/**
+ * {@include string/to/index.md}
+ */
+function to(value) {
+    return `${value}`;
+}
+
+export { to };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duplojs/utils",
-  "version": "1.4.36",
+  "version": "1.4.38",
   "author": {
     "name": "mathcovax",
     "url": "https://github.com/mathcovax"