@cto.af/utils 1.3.1 → 1.3.5

package/lib/index.d.ts

@@ -1,10 +1,30 @@
+//#region src/index.d.ts
+declare class AssertionError extends Error {
+  constructor(actual: unknown, expected: unknown, message?: string);
+  toString(): string;
+}
+/**
+ * Very simplified assert, which will work in the browser.
+ *
+ * @param value Any value that should be truthy.
+ * @param message Optional message.
+ * @throws {AssertionError} If value is falsy.
+ */
+declare function assert(value: unknown, message?: string): asserts value;
+type Pretty<T> = { [K in keyof T]: T[K] } & {};
+interface ErrnoException extends Error {
+  errno?: number | undefined;
+  code?: string | undefined;
+  path?: string | undefined;
+  syscall?: string | undefined;
+}
 /**
  * Is the object an ErrnoException?
  *
  * @param e Object to check.
  * @returns Type assertion.
  */
-declare function isErrno(e: unknown): e is NodeJS.ErrnoException;
+declare function isErrno(e: unknown): e is ErrnoException;
 /**
  * Does the error contain a specific code?
  *
@@ -15,7 +35,7 @@ declare function isErrno(e: unknown): e is NodeJS.ErrnoException;
  */
 declare function errCode(e: unknown, code: string | number): boolean;
 interface CiOptions {
-    CI?: boolean;
+  CI?: boolean;
 }
 /**
  * Is the current environment CI-like.
@@ -25,9 +45,9 @@ interface CiOptions {
  */
 declare function isCI(opts?: CiOptions): boolean;
 interface PromiseWithResolvers<T> {
-    promise: Promise<T>;
-    resolve(value: T | PromiseLike<T>): void;
-    reject(reason?: any): void;
+  promise: Promise<T>;
+  resolve(value: T | PromiseLike<T>): void;
+  reject(reason?: any): void;
 }
 /**
  * Polyfill for Promise.withResolvers.  Once node 22 is the minimum version,
@@ -42,7 +62,7 @@ declare function promiseWithResolvers<T>(): PromiseWithResolvers<T>;
 /**
  * Get the names of the keys of an options type, from the defaults.
  *
- * @template T
+ * @template T Options type.
  * @param defaults Default values for the options.
  * @returns List of keys of the given object.
  */
@@ -52,19 +72,49 @@ declare function nameSet<T extends object>(defaults: T): Set<keyof T>;
  * Useful for validating inputs to select.
  *
  * @param sets Sets to check.
- * @throws If sets are the wrong type.
+ * @throws {AssertionError} If sets are the wrong type.
  */
 declare function assertDisjoint(...sets: (Set<string> | string[] | object)[]): void;
+/**
+ * Select with a defaults object, a list of keys, or a set of keys.  The
+ * set of keys might perform better, but we can't extract types from it.
+ *
+ * @template T Options object, where most properties are optional.
+ */
+type Selector<T extends object> = Partial<T> | (keyof T)[] | Set<keyof T>;
+/**
+ * A defaults object extracts a required subset of T.
+ * A list of keys extracts a partial subset of T with those possible keys.
+ * A Set extracts a full partial of T.
+ *
+ * @template T Options object, where most properties are optional.
+ * @template U Selector.
+ */
+type Selected<T extends object, U extends Selector<T>> = U extends Partial<T> ? U : U extends (keyof T)[] ? Pretty<Partial<Pick<T, U[number]>>> : Partial<T>;
+/**
+ * The keys that were selected.
+ *
+ * @template T Options object, where most properties are optional.
+ * @template U Selector.
+ */
+type SelectedKeys<T extends object, U extends Selector<T>> = U extends Partial<T> ? keyof U : U extends (keyof T)[] ? U[number] : never;
 /**
  * Select some properties from an object into multiple other objects.
+ * All unselected fields will be contained in a final object for the
+ * "leftovers", meaning there will always be at least one element in the
+ * result array.  If the first selector is a set of defaults, the type from
+ * that object will be copied to the first element of the result array
+ * and subtracted from the rest of the results.
  *
  * @template T Composed options object.
+ * @template U May be a Required<Partial<T>> type.
  * @param obj The source object.
- * @param args Arrays of strings to select into the result
- *   objects.
- * @returns {Partial<Record<keyof T, any>>[]} One object for each of args,
+ * @param defaultsU Defaults object or field names.
+ * @returns One object for each of args,
  *   plus an extra one for everything that was left over.
  */
-declare function select<T extends object>(obj: T, ...args: (Partial<T> | (keyof T)[] | Set<keyof T>)[]): Partial<T>[];
-
-export { type CiOptions, type PromiseWithResolvers, assertDisjoint, errCode, isCI, isErrno, nameSet, promiseWithResolvers, select };
+declare function select<T extends object, U extends Selector<T>>(obj: T, defaultsU: U): [Selected<T, U>, Pretty<Omit<T, SelectedKeys<T, U>>>];
+declare function select<T extends object, U extends Selector<T>, V extends Selector<T>>(obj: T, defaultsU: U, defaultsV: V): [Selected<T, U>, Selected<T, V>, Pretty<Omit<T, SelectedKeys<T, U> | SelectedKeys<T, V>>>];
+declare function select<T extends object, U extends Selector<T>, V extends Selector<T>, W extends Selector<T>>(obj: T, defaultsU: U, defaultsV: V, defaultsW: W): [Selected<T, U>, Selected<T, V>, Selected<T, W>, Pretty<Omit<T, SelectedKeys<T, U> | SelectedKeys<T, V> | SelectedKeys<T, W>>>];
+//#endregion
+export { AssertionError, CiOptions, ErrnoException, Pretty, PromiseWithResolvers, Selected, SelectedKeys, Selector, assert, assertDisjoint, errCode, isCI, isErrno, nameSet, promiseWithResolvers, select };

package/lib/index.js

@@ -1 +1 @@
-import u from"assert/strict";function T(e){return e instanceof Error&&Object.prototype.hasOwnProperty.call(e,"code")}function v(e,r){if(!T(e))return!1;switch(typeof r){case"string":return e.code===r;case"number":return e.errno===r}throw new TypeError(`Invalid code: ${JSON.stringify(r)}`)}function b(e){if(e&&"CI"in e)return!!e.CI;let{env:r}=process;return!!(r.CI||r.CONTINUOUS_INTEGRATION||r.BUILD_NUMBER||r.RUN_ID)}var a=()=>{};function d(){let e=a,r=a;return{promise:new Promise((n,s)=>{e=n,r=s}),resolve:e,reject:r}}function p(e){return new Set(Object.keys(e))}function k(...e){let r=new Set;for(let t of e){let n=null;if(Array.isArray(t))n=t;else if(t instanceof Set)n=t;else if(typeof t=="object"&&t)n=Object.keys(t);else throw new Error("Invalid set");for(let s of n)u(!r.has(s)),r.add(s)}}function m(e,...r){let t=[],n=r.map(o=>{let i=Object.create(null);if(Array.isArray(o))return t.push(new Set(o)),i;if(o instanceof Set)return t.push(o),i;if(!o||typeof o!="object")throw new Error("Invalid set");return t.push(p(o)),Object.assign(i,o)}),s=Object.create(null);if(n.push(s),!e)return n;for(let[o,i]of Object.entries(e)){let f=!1;t.forEach((c,l)=>{!f&&c.has(o)&&(f=!0,n[l][o]=i)}),f||(s[o]=i)}return n}export{k as assertDisjoint,v as errCode,b as isCI,T as isErrno,p as nameSet,d as promiseWithResolvers,m as select};
+var e=class extends Error{constructor(e,t,n){let r=!1;n||(n=`The expression evaluated to a falsy value:\n\n  assert(${e})\n`,r=!0),super(n),Object.assign(this,{code:`ERR_ASSERTION`,actual:e,expected:t,operator:`==`,generatedMessage:r})}toString(){return`AssertionError [ERR_ASSERTION]: ${this.message}`}};function t(t,n){if(!t)throw new e(t,!0,n)}function n(e){return e instanceof Error&&Object.prototype.hasOwnProperty.call(e,`code`)}function r(e,t){if(!n(e))return!1;switch(typeof t){case`string`:return e.code===t;case`number`:return e.errno===t}throw TypeError(`Invalid code: ${JSON.stringify(t)}`)}function i(e){if(e&&`CI`in e)return!!e.CI;if(typeof process>`u`)return!1;let{env:t}=process;return!!(t.CI||t.CONTINUOUS_INTEGRATION||t.BUILD_NUMBER||t.RUN_ID)}const a=()=>void 0;function o(){let e=a,t=a;return{promise:new Promise((n,r)=>{e=n,t=r}),resolve:e,reject:t}}function s(e){return new Set(Object.keys(e))}function c(...e){let n=new Set;for(let r of e){let e=null;if(Array.isArray(r))e=r;else if(r instanceof Set)e=r;else if(typeof r==`object`&&r)e=Object.keys(r);else throw Error(`Invalid set`);for(let r of e)t(!n.has(r),r),n.add(r)}}function l(e,...t){let n=[],r=t.map(e=>{let t=Object.create(null);if(e instanceof Set)return n.push(e),t;if(Array.isArray(e))return n.push(new Set(e)),t;if(!e||typeof e!=`object`)throw Error(`Invalid set: ${e}`);return n.push(s(e)),Object.assign(t,e)}),i=Object.create(null);if(r.push(i),!e)return r;for(let[t,a]of Object.entries(e)){let e=!1;n.forEach((n,i)=>{!e&&n.has(t)&&(e=!0,r[i][t]=a)}),e||(i[t]=a)}return r}export{e as AssertionError,t as assert,c as assertDisjoint,r as errCode,i as isCI,n as isErrno,s as nameSet,o as promiseWithResolvers,l as select};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cto.af/utils",
-  "version": "1.3.1",
+  "version": "1.3.5",
   "decription": "",
   "main": "lib/index.js",
   "files": [
@@ -18,7 +18,7 @@
   "bugs": {
     "url": "https://github.com/cto-af/utils/issues"
   },
-  "packageManager": "pnpm@10.15.0",
+  "packageManager": "pnpm@10.20.0",
   "engines": {
     "node": ">=20"
   }