@lionweb/ts-utils 0.7.0-beta.18 → 0.7.0-beta.19

package/CHANGELOG.md

@@ -5,4 +5,5 @@
 * Initial creation and publication of this package, as an extraction and de-duplication from `@lionweb/core`, `@lionweb/utilities`, `@lionweb/class-core`, and `@lionweb/validation`.
 * Add 'mapFrom' function that maps an array to a map, using given key and value functions.
 * Introduce explicit types for `nested{1,2,3}Mapper` functions.
+* Package `src/` again (— i.e., don't ignore for NPM packaging.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lionweb/ts-utils",
-    "version": "0.7.0-beta.18",
+    "version": "0.7.0-beta.19",
     "description": "Utilities for LionWeb JSON",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/src/arrays.ts

@@ -0,0 +1,49 @@
+/**
+ * Feature's values are often persisted as either `undefined`, a single object, or an array of objects,
+ * regardless of the actual cardinality of that feature.
+ * This is e.g. the case when parsing an Ecore XML metamodel file.
+ * This type definition captures that phenomenon.
+ */
+export type AnyNumberOf<T> = undefined | T | T[]
+
+/**
+ * Turns a {@link AnyNumberOf feature's value} into an array of objects
+ * (possibly empty), regardless of the feature's cardinality and how its
+ * value happened to be parsed.
+ */
+export const asArray = <T>(thing: AnyNumberOf<T>): T[] => {
+    if (thing === undefined) {
+        return []
+    }
+    if (Array.isArray(thing)) {
+        return thing
+    }
+    return [thing]
+}
+
+/**
+ * @return a view of the given array of items with duplicates removed.
+ */
+export const uniquesAmong = <T>(ts: T[]): T[] =>
+    [...new Set(ts)]
+
+
+/**
+ * @return the defined values of given type (parameter) `T` from the given array,
+ * leaving out the `null` or `undefined` values.
+ */
+export const keepDefineds = <T>(ts: (T | null | undefined)[]): T[] =>
+    ts.filter((t) => t !== undefined && t !== null) as T[]
+
+
+/**
+ * @return the last element of the given `ts` array.
+ * @throws an {@link Error} if the array is empty, so it doesn't have a last element.
+ */
+export const lastOfArray = <T>(ts: T[]): T => {
+    if (ts.length === 0) {
+        throw new Error(`empty array doesn't have a last element`)
+    }
+    return ts[ts.length - 1]
+}
+

package/src/cycles.ts

@@ -0,0 +1,31 @@
+export type NextsFunction<T> = (t: T) => T[]
+
+
+/**
+ * Compute whether there's a cycle of dependencies, starting with `thing` and computing "nexts" with the given `nextsFunction`.
+ * @return An array with a cycle of "things", starting at the given `thing`.
+ *  An array of length 0 means: the given `thing` is not part of any cycle.
+ */
+export const cycleWith = <T>(thing: T, nextsFunction: NextsFunction<T>): T[] => {
+
+    const result = visit<T>(thing, [], nextsFunction)
+    return result.length > 0 && result[result.length - 1] === thing
+        ? result
+        : []
+}
+
+const visit = <T>(current: T, chain: T[], nextsFunction: NextsFunction<T>): T[] => {
+    if (chain.indexOf(current) > -1) {
+        // Add current to end, so we know what sub-array constitutes the actual cycle:
+        return [ ...chain, current ]
+    }
+    const extendedChain = [ ...chain, current ]
+    for (const dependency of nextsFunction(current)) {
+        const recursion = visit(dependency, extendedChain, nextsFunction)
+        if (recursion.length > 0) {
+            return recursion
+        }
+    }
+    return []
+}
+

package/src/graphs.ts

@@ -0,0 +1,36 @@
+// NB This is an almost identical copy of packages/core/utils/recursion.ts
+//    Copied to avoid package dependencies
+/**
+ * Type def. of a generic "flatMap" function.
+ */
+export type ResultMapper<T, R> = (t: T) => R[]
+
+/**
+ * Returns a function that performs a "flatMap" on a graph that's specified as a start vertex. and a function that computes (outgoing) edges.
+ * The "flatMap" is performed depth-first, and doesn't loop on cycles.
+ * 
+ * @param mapper The function that calculates the result values
+ * @param nextVertices  The function that calculates the next edges to visit.
+ * @returns A function that takes a starting vertex and recursively calculates the result values for each vertex visited.
+ */
+export const visitAndMap =
+    <T, R>(mapper: ResultMapper<T, R>, nextVertices: (t: T) => T[]): ResultMapper<T, R> =>
+    (startVertex: T): R[] => {
+        const visited: T[] = []
+        const results: R[] = []
+        const recurse = (t: T) => {
+            if (visited.indexOf(t) > -1) {
+                return
+            }
+            visited.push(t)
+            results.push(...mapper(t))
+            nextVertices(t).forEach(recurse)
+        }
+        recurse(startVertex)
+        return results
+    }
+
+/** 
+ * A mapper function that returns the node itself as result
+ */
+export const selfMapper = <T>(t: T) => [t]

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./arrays.js"
+export * from "./cycles.js"
+export * from "./graphs.js"
+export * from "./json.js"
+export * from "./maps.js"
+export * from "./nested-maps.js"
+export * from "./recursion.js"
+export * from "./string-sorting.js"
+export * from "./string-mapping.js"
+export * from "./toposort.js"

package/src/json.ts

@@ -0,0 +1,8 @@
+/** Normalized JSON with 4 spaces as indent */
+export const asPrettyJsonString = (obj: unknown): string => {
+    return JSON.stringify(obj, null, 4);
+}
+/** Minimal JSON with no spaces as indent */
+export const asMinimalJsonString  = (obj: unknown): string => {
+    return JSON.stringify(obj, null, 0);
+}

package/src/maps.ts

@@ -0,0 +1,82 @@
+/**
+ * Computes a map id -> thing with id.
+ */
+export const byIdMap = <T extends { id: string }>(ts: T[]): { [id: string]: T } => {
+    const map: { [id: string]: T } = {}
+    ts.forEach((t) => {
+        map[t.id] = t
+    })
+    return map
+    // TODO  -> Object.fromEntries(...) but what happens then with duplicate IDs?
+}
+
+
+/**
+ * Groups a list of items according to a computed key.
+ */
+export const groupBy = <T>(ts: T[], keyFunc: (t: T) => string): Record<string, T[]> => {
+    const map: Record<string, T[]> = {}
+    ts.forEach((t) => {
+        const key = keyFunc(t)
+        let list = map[key]
+        if (list === undefined) {
+            list = []
+            map[key] = list
+        }
+        list.push(t)
+    })
+    return map
+}
+
+
+/**
+ * Filters the values of a map/record according the given predicate.
+ */
+export const filterValues = <V>(map: Record<string, V>, predicate: (v: V) => boolean): Record<string, V> =>
+    Object.fromEntries(
+        Object.entries(map)
+            .filter(([_, value]) => predicate(value))
+    )
+
+
+/**
+ * Computes the given items whose computed keys are duplicates, as a map key &rarr; items.
+ */
+export const duplicatesAmong = <T>(ts: T[], keyFunc: (t: T) => string): Record<string, T[]> =>
+    filterValues(groupBy(ts, keyFunc), (ts) => ts.length > 1)
+
+
+/**
+ * Maps the values of a map/record according to the given mapping function.
+ */
+export const mapValues = <V, W>(map: Record<string, V>, valFunc: (v: V) => W): Record<string, W> =>
+    Object.fromEntries(
+        Object.entries(map)
+            .map(([key, value]) => [key, valFunc(value)])
+    )
+
+
+/**
+ * Gets the value under the given key from the given map,
+ * creating that value when that key wasn't present yet.
+ * This allows for convenient “chaining” of map-lookups,
+ * e.g. to build up nested maps.
+ */
+export const lazyMapGet = <T>(map: { [key: string]: T }, key: string, createThunk: () => T): T => {
+    if (key in map) {
+        return map[key]
+    }
+    const value = createThunk()
+    map[key] = value
+    return value
+}
+
+
+/**
+ * @return a map with each key-value pair the result of mapping an item in the given list using the given key and value functions.
+ */
+export const mapFrom = <T, V>(ts: T[], keyFunc: (t: T) => string, valueFunc: (t: T) => V): Record<string, V> =>
+    Object.fromEntries(
+        ts.map((t) => [keyFunc(t), valueFunc(t)])
+    )
+

package/src/nested-maps.ts

@@ -0,0 +1,99 @@
+import { groupBy } from "./maps.js"
+
+
+export type Nested1Map<T> = Record<string, T> // (for conceptual continuity)
+export type Nested2Map<T> = Record<string, Record<string, T>>
+export type Nested3Map<T> = Record<string, Record<string, Record<string, T>>>
+
+export type Nested1Mapper<T, R> = (nested1Map: Nested1Map<T>) => Nested1Map<R>
+export const mapValuesMapper =
+    <T, R>(valueMapFunc: (t: T) => R): Nested1Mapper<T, R> =>
+    (map: Record<string, T>): Record<string, R> =>
+        Object.fromEntries(Object.entries(map).map(([key, value]) => [key, valueMapFunc(value)]))
+// === mapValues(map, valueFunc)
+
+export type Nested2Mapper<T, R> = (nested2Map: Nested2Map<T>) => Nested2Map<R>
+export const nested2Mapper = <T, R>(valueMapFunc: (t: T) => R): Nested2Mapper<T, R> =>
+    mapValuesMapper(mapValuesMapper(valueMapFunc))
+
+export type Nested3Mapper<T, R> = (nested3Map: Nested3Map<T>) => Nested3Map<R>
+export const nested3Mapper = <T, R>(valueMapFunc: (t: T) => R): Nested3Mapper<T, R> =>
+    mapValuesMapper(nested2Mapper(valueMapFunc))
+
+/**
+ * Return a function that groups an array of things using a group function as a
+ *  map : string (group key) &rarr; array of grouped things.
+ */
+export const grouper =
+    <T>(key1Func: (t: T) => string): ((ts: T[]) => Nested1Map<T[]>) =>
+        (ts: T[]) =>
+            groupBy(ts, key1Func)
+
+/**
+ * Return a function that groups an array of things using two group functions as a nested map
+ *  map : string (group key 1) &rarr;
+ *      map : string (group key 2) &rarr; array of grouped things.
+ */
+export const nested2Grouper =
+    <T>(key1Func: (t: T) => string, key2Func: (t: T) => string): ((ts: T[]) => Nested2Map<T[]>) =>
+        (ts: T[]) =>
+            mapValuesMapper(grouper(key2Func))(grouper(key1Func)(ts))
+// === mapValuesMapper((vs) => groupBy(vs, key2Func))(groupBy(ts, key1Func))
+
+/**
+ * Return a function that groups an array of things using two group functions as a nested map
+ *  map : string (group key 1) &rarr;
+ *      map : string (group key 2) &rarr;
+ *          map : string (group key 3) &rarr; array of grouped things.
+ */
+export const nested3Grouper =
+    <T>(key1Func: (t: T) => string, key2Func: (t: T) => string, key3Func: (t: T) => string): ((ts: T[]) => Nested3Map<T[]>) =>
+        (ts: T[]) =>
+            mapValuesMapper(nested2Grouper(key2Func, key3Func))(grouper(key1Func)(ts))
+
+/**
+ * Flat-maps over the values of a
+ *  map : string (group key) &rarr; values
+ * using the map function, which is also provided with the keys.
+ */
+export const flatMapValues = <T, R>(map: Record<string, T>, mapFunc: (t: T, key1: string) => R): R[] =>
+    Object
+        .entries(map)
+        .map(
+            ([key1, t]) =>
+                mapFunc(t, key1)
+        )
+
+/**
+ * Flat-maps over the values of a nested map
+ *  map : string (group key 1) &rarr;
+ *      map: string (group key 2) &rarr; values
+ * using the map function, which is also provided with the keys.
+ */
+export const nestedFlatMap2 = <T, R>(nested2Map: Nested2Map<T>, map2Func: (t: T, key1: string, key2: string) => R): R[] =>
+    Object
+        .entries(nested2Map)
+        .flatMap(
+            ([key1, nestedMap1]) =>
+                flatMapValues(nestedMap1, (t, key2) =>
+                    map2Func(t, key1, key2)
+                )
+        )
+
+/**
+ * Flat-maps over the values of a nested map
+ *  map : string (group key 1) &rarr;
+ *      map: string (group key 2) &rarr;
+ *           map: string (group key 3) &rarr; values
+ * using the map function, which is also provided with the keys.
+ */
+export const nestedFlatMap3 = <T, R>(nested3Map: Nested3Map<T>, map3Func: (t: T, key1: string, key2: string, key3: string) => R): R[] =>
+    Object
+        .entries(nested3Map)
+        .flatMap(
+            ([key1, nestedMap2]) =>
+                nestedFlatMap2(nestedMap2, (t, key2, key3) =>
+                    map3Func(t, key1, key2, key3)
+                )
+        )
+

package/src/recursion.ts

@@ -0,0 +1,41 @@
+/**
+ * Type def. of a generic "flatMap" function.
+ */
+type FlatMapper<T, R> = (t: T) => R[]
+
+/**
+ * Performs a "flatMap" on a graph that's specified as a start vertex and a function that computes (outgoing) edges.
+ * The "flatMap" is performed depth-first, and doesn't loop on cycles.
+ */
+const flatMapNonCyclingFollowing = <T, R>(
+    mapper: FlatMapper<T, R>,
+    nextVertices: (t: T) => T[]
+): FlatMapper<T, R> =>
+    (startVertex: T): R[] => {
+        const visited: T[] = []
+        const rs: R[] = []
+        const recurse = (t: T) => {
+            if (visited.indexOf(t) > -1) {
+                return
+            }
+            visited.push(t)
+            rs.push(...mapper(t))
+            nextVertices(t).forEach(recurse)
+        }
+        recurse(startVertex)
+        return rs
+    }
+
+
+const trivialFlatMapper = <T>(t: T) => [t]
+
+
+export type {
+    FlatMapper
+}
+
+export {
+    flatMapNonCyclingFollowing,
+    trivialFlatMapper
+}
+

package/src/string-mapping.ts

@@ -0,0 +1,38 @@
+/**
+ * A type for functions that map any number of strings (as a variadic argument) to a single string.
+ */
+export type StringsMapper = (...strings: string[]) => string
+
+/**
+ * A type for functions that map strings to strings.
+ */
+export type StringMapper = (str: string) => string
+
+
+/**
+ * @return a {@link StringsMapper function} that concatenates the strings passed into it, using the given separator string.
+ */
+export const concatenator = (separator: string): StringsMapper =>
+    (...strings) => strings.join(separator)
+
+/**
+ * @return a {@link StringsMapper function} that picks the last string of the strings passed into it.
+ * (This means that there must always be at least one string passed in.)
+ */
+export const lastOf: StringsMapper =
+    (...strings) => strings[strings.length - 1]
+
+/**
+ * @return a {@link StringsMapper function} that chains the given {@link StringsMapper functions} (at least 1),
+ * in thar order.
+ * (This is straightforward functional composition.)
+ */
+export const chain = (stringsMapper: StringsMapper, ...stringMappers: StringMapper[]): StringsMapper =>
+    (...strings: string[]) => {
+        let result = stringsMapper(...strings)
+        stringMappers.forEach((mapper) => {
+            result = mapper(result)
+        })
+        return result
+    }
+

package/src/string-sorting.ts

@@ -0,0 +1,29 @@
+/**
+ * Various functional utilities for sorting things.
+ */
+
+
+type Comparer<T> = (l: T, r: T) => number
+
+const stringCompare: Comparer<string> = (l, r): number =>
+    l === r ? 0 : (l > r ? 1 : -1)
+
+const stringyCompare = <T>(keyFunc: (t: T) => string): Comparer<T> =>
+    (l: T, r: T) => stringCompare(keyFunc(l), keyFunc(r))
+
+export const sortByStringKey = <T>(ts: T[], keyFunc: (t: T) => string) =>
+    [...ts].sort(stringyCompare(keyFunc))
+
+
+export type StringSorter = (strings: string[]) => string[]
+
+const sortedStringsWith = (strMap: (str: string) => string): StringSorter =>
+    (strings) => {
+        strings.sort((l, r) => strMap(l).localeCompare(strMap(r)))
+        return strings
+    }
+
+export const sortedStrings = sortedStringsWith((str) => str)
+
+export const sortedStringsByUppercase = sortedStringsWith((str) => str.toUpperCase())
+

package/src/toposort.ts

@@ -0,0 +1,46 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Computes the topological order of the transitive closure of the graph with the given vertices and edges given by the edge function,
+ * or returns {@code false} if there's a cycle.
+ */
+export const dependencyOrderOf = <T>(vertices: T[], edgesOf: (vertex: T) => T[]): T[] | false => {
+    const ordered: T[] = []
+
+    const visit = (current: T, chain: T[]) => {
+        if (ordered.indexOf(current) > -1) {
+            return false
+        }
+        if (chain.indexOf(current) > -1) {
+            return true
+        }
+        const extendedChain = [ ...chain, current ]
+        const hasCycle = edgesOf(current).some(
+            (edge) => visit(edge, extendedChain)
+        )
+        ordered.push(current)
+        return hasCycle
+    }
+
+    const hasCycle = vertices.some(
+        (vertex) => visit(vertex, [])
+    )
+
+    return hasCycle ? false : ordered
+}
+