@normed/bundle 4.1.0 → 4.2.1

package/bundles/log.d.ts

@@ -1,5 +1,5 @@
 type LogFunction = (...message: any[]) => void;
-type LogLevel = "debug" | "verbose" | "info" | "warn" | "error" | "critical";
+export type LogLevel = "debug" | "verbose" | "info" | "warn" | "error" | "critical";
 export declare function setMinLogLevel(level: number | LogLevel): void;
 declare const logFunctions: {
     [level in LogLevel]: LogFunction;

package/bundles/plugins.d.ts

@@ -0,0 +1,27 @@
+export declare namespace BundlePlugin {
+    type Passthrough<T, A extends unknown[] = never[]> = (v: T, ...args: A) => T | Promise<T>;
+    type Alteration<T, R, A extends unknown[] = never[]> = (v: T, ...args: A) => R | Promise<R>;
+    type Event<T, A extends unknown[] = never[]> = (v: T, ...args: A) => void | Promise<void>;
+    type Any = Passthrough<any, any[]> | Alteration<any, any, any[]> | Event<any, any[]>;
+}
+import type { Entrypoint, Builder, BuilderBuildResult } from "./types";
+import type { NoMatchingBuilder } from "./errors";
+type EstablishedPlugins = {
+    preBuild?: BundlePlugin.Passthrough<Map<{
+        builder: Builder;
+    }, Entrypoint[]>>;
+    postBuild?: BundlePlugin.Passthrough<BuilderBuildResult, [
+        {
+            builder: Builder;
+            entrypoints: Entrypoint[];
+            duration_ms: number;
+        }
+    ]>;
+    missingBuilders?: BundlePlugin.Passthrough<NoMatchingBuilder[]>;
+    initialEntrypoints?: BundlePlugin.Passthrough<(NoMatchingBuilder | Entrypoint)[]>;
+    discoveredEntrypoints?: BundlePlugin.Passthrough<Entrypoint[]>;
+};
+export type BundlePlugins = EstablishedPlugins & {
+    [key: Exclude<string, keyof EstablishedPlugins>]: BundlePlugin.Any;
+};
+export {};

package/bundles/types.d.ts

@@ -2,11 +2,32 @@ import { Chalk } from "chalk";
 import type { BuildOptions as ESBuild_BuildOptions, TsconfigRaw } from "esbuild";
 import { RefinementFunction } from "@normed/refinements";
 import type { FileInfo } from "./File";
+import { ErrorLog } from "./errors";
 export type Platform = "web" | "server" | "library";
+declare class DirectoryInfo {
+    path: string;
+    constructor(path: string);
+}
+export type BuilderBuildResult = {
+    completed: boolean;
+    watchFiles: FileInfo[];
+    watchDirs: DirectoryInfo[];
+    producedFiles: FileInfo[];
+} & ErrorLog;
+export type FinalBuilderBuildResult = BuilderBuildResult & {
+    entrypoints: Entrypoint[];
+    duration_ms: number;
+    children: AnnotatedBuilderBuildResult[];
+};
+export type AnnotatedBuilderBuildResult = BuilderBuildResult & {
+    entrypoints: Entrypoint[];
+    builder: Builder;
+    duration_ms: number;
+};
 export type Builder = {
     inExt: (string | RegExp)[];
     outExt: string | null | ((inext: string) => string);
-    build(entrypoints: Entrypoint[]): Promise<void>;
+    build(entrypoints: Entrypoint[]): Promise<BuilderBuildResult>;
     name: string;
     color: Chalk;
 };
@@ -90,3 +111,4 @@ export type APIOptions_Clean = {
     outdir?: string;
 };
 export type APIOptions = APIOptions_Bundle & APIOptions_Clean;
+export {};

package/bundles/utils.d.ts

@@ -4,11 +4,88 @@ import jsonStableStringify from "json-stable-stringify";
 export declare const stringify: typeof jsonStableStringify;
 export declare function escapeRegExp(string: string): string;
 /**
- * // TODO
+ * Groups an array of objects based on the results of applying multiple key extraction functions.
+ * Objects are placed in the same group if all extraction functions return the same values for them.
  *
- * n.b. Subgroups are compared with referential equality (===)
+ * @param objs - The array of objects to group
+ * @param extractSubgroupFuncs - An array of functions that extract values from each object
+ * @returns An array of arrays, where each inner array contains objects that belong to the same group
+ *
+ * n.b. Subgroups are compared with referential equality (===), so primitive values are recommended.
+ *
+ * @example
+ * // Group people by both age and city
+ * const people = [
+ *   { name: 'Alice', age: 30, city: 'New York' },
+ *   { name: 'Bob', age: 30, city: 'Boston' },
+ *   { name: 'Charlie', age: 30, city: 'New York' },
+ *   { name: 'Dave', age: 25, city: 'Boston' }
+ * ];
+ *
+ * const groups = groupBy(people, [
+ *   person => person.age,
+ *   person => person.city
+ * ]);
+ *
+ * // Result:
+ * // [
+ * //   [{ name: 'Alice', age: 30, city: 'New York' }, { name: 'Charlie', age: 30, city: 'New York' }],
+ * //   [{ name: 'Bob', age: 30, city: 'Boston' }],
+ * //   [{ name: 'Dave', age: 25, city: 'Boston' }]
+ * // ]
  */
 export declare function groupBy<O>(objs: O[], extractSubgroupFuncs: ((o: O) => unknown)[]): O[][];
+/**
+ * Groups an array of objects based on named key extraction functions.
+ * Objects are placed in the same group if all extracted values match.
+ * Unlike `groupBy`, this function preserves the names of the keys used for grouping.
+ *
+ * @param objs - The array of objects to group
+ * @param extractKeyFuncs - An object where each key is a name and each value is a function
+ *                         that extracts a value from an object. These extracted values form
+ *                         the composite key for grouping.
+ * @returns A Map where:
+ *          - Keys are objects with the same structure as extractKeyFuncs, but containing
+ *            the extracted values instead of functions
+ *          - Values are arrays of objects that share the same extracted values
+ *
+ * @example
+ * // Group people by both age and city, with named keys
+ * const people = [
+ *   { name: 'Alice', age: 30, city: 'New York' },
+ *   { name: 'Bob', age: 30, city: 'Boston' },
+ *   { name: 'Charlie', age: 30, city: 'New York' },
+ *   { name: 'Dave', age: 25, city: 'Boston' }
+ * ];
+ *
+ * const grouped = keyBy(people, {
+ *   age: person => person.age,
+ *   location: person => person.city
+ * });
+ *
+ * // Result is a Map with these entries:
+ * // Map(3) {
+ * //   { age: 30, location: 'New York' } => [
+ * //     { name: 'Alice', age: 30, city: 'New York' },
+ * //     { name: 'Charlie', age: 30, city: 'New York' }
+ * //   ],
+ * //   { age: 30, location: 'Boston' } => [
+ * //     { name: 'Bob', age: 30, city: 'Boston' }
+ * //   ],
+ * //   { age: 25, location: 'Boston' } => [
+ * //     { name: 'Dave', age: 25, city: 'Boston' }
+ * //   ]
+ * // }
+ *
+ * // The Map keys preserve the property names from extractKeyFuncs
+ * // You can iterate over the Map entries to access both the grouping keys and values:
+ * for (const [key, group] of grouped.entries()) {
+ *   console.log(`Age ${key.age} in ${key.location}: ${group.length} people`);
+ * }
+ */
+export declare function keyBy<O, K extends Record<string, (o: O) => unknown>>(objs: O[], extractKeyFuncs: K): Map<{
+    [P in keyof K]: ReturnType<K[P]>;
+}, O[]>;
 /**
  * Divides a list into two sub-lists.
  * Wlements that pass the divider function are in the left list, elements that do not are in the right list.
@@ -19,7 +96,13 @@ export declare function groupBy<O>(objs: O[], extractSubgroupFuncs: ((o: O) => u
  * @param (v: (A | B)) => v is a -  divider - The divider function - potentially a type guard.
  * @returns [A[], B[]]
  */
-export declare function divide<A, B>(list: (A | B)[], divider: (v: A | B) => v is A): [A[], B[]];
+export declare function divide<B, A extends B>(list: B[], divider: (v: B) => v is A): [A[], Exclude<B, A>[]];
+export declare function divide<T>(list: T[], divider: (v: T) => boolean): [T[], T[]];
+export declare function isNotX<X>(x: X): <T>(v: X | T) => v is T;
+export declare const isNot: {
+    undefined: <T>(v: T | undefined) => v is T;
+    null: <T>(v: T | null) => v is T;
+};
 export declare function join(...parts: (string | undefined)[]): string;
 export declare function write(to: string, data: string): Promise<void>;
 export declare function copy(from: string, to: string): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@normed/bundle",
   "author": "Normal Gaussian <normed.bundle@normal-gaussian.com>",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "bin": "bundles/bin/cli.js",
   "main": "bundles/index.js",
   "types": "dist",
@@ -60,6 +60,7 @@
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
     "esbuild": "^0.25.5",
     "json-stable-stringify": "^1.3.0",
+    "pino": "^9.7.0",
     "typescript": "^5.8.3"
   },
   "license": "MIT",