artemis-kit

TypeScript/JavaScript utility library. Tree-shakeable, split exports per module.

Install: pnpm install @warkypublic/artemis-kit

Modules

collections

import { groupBy, keyBy, uniqueBy, partition } from "@warkypublic/artemis-kit/collections"

const rows = [
  { id: 1, team: "red", score: 10 },
  { id: 2, team: "blue", score: 5 },
  { id: 3, team: "red", score: 20 },
]
const teams = groupBy(rows, row => row.team) // Map<string, Row[]>
const byId = keyBy(rows, row => row.id) // Map<number, Row>
const representatives = uniqueBy(rows, row => row.team) // first row per team
const [high, low] = partition(rows, row => row.score >= 10)

All helpers accept readonly arrays and preserve input order without mutating the input. Items retain their original references. groupBy and keyBy return Map instances; keys use Map/Set equality (object identity, with NaN equal to NaN). keyBy keeps the last item for a duplicate key; uniqueBy keeps the first. partition returns [matching, nonMatching] arrays.

sorting

import { compareBy, chainComparators, createComparator } from "@warkypublic/artemis-kit/sorting"

const sorted = [...rows].sort(chainComparators(
  compareBy<(typeof rows)[number]>(row => row.team, { locale: "en" }),
  compareBy<(typeof rows)[number]>(row => row.score, { direction: "desc" }),
))
const labels = ["item10", "item2"].sort(createComparator({ locale: "en" }))
// ["item2", "item10"]

Comparators accept strings, numbers, dates, null, and undefined. Options:

| Option | Default | Behavior | |---|---|---| | direction | "asc" | "asc" or "desc" | | empty | "last" | "first" or "last", independent of direction | | locale | Runtime locale | Locale string or ordered list of locales | | collator | { numeric: true } | Intl.Collator options, created once per comparator |

Empty values are null, undefined, "", NaN, and invalid dates. Whitespace strings are not empty. Numbers compare numerically and dates by timestamp. Mixed types sort numbers, then dates, then strings in ascending order; strings are never coerced to numbers. chainComparators returns zero when all criteria tie.

Use compareBy to sort rows with missing values: JavaScript's Array.sort always moves bare undefined elements to the end without invoking the comparator, even with empty: "first". Sorting mutates the array; copy it first as shown above.

These helpers and their types are also available from the package root.

strings

import { ... } from "@warkypublic/artemis-kit/strings"

| Function | Signature | Description | |---|---|---| | trimLeft | (str, chars?, times?) | Trim chars from left, Unicode-safe | | trimRight | (str, chars?, times?) | Trim chars from right, Unicode-safe | | replaceStr | (str, search, replace) | Replace first occurrence | | replaceStrAll | (str, search, replace) | Replace all occurrences | | initCaps | (sentence) | Capitalize first letter of each word | | titleCase | (sentence) | Title case, skips articles/conjunctions | | camelCase | (sentence) | Convert to camelCase | | snakeCase | (sentence) | Convert to snake_case | | reverseSnakeCase | (sentence) | snake_case → camelCase | | splitCamelCase | (sentence) | camelCase → space-separated words | | formatNumber | (value, locale, options?) | Locale-aware number formatting via Intl | | formatCurrency | (value, locale, currency) | Locale-aware currency formatting | | formatDate | (date, locale, options?) | Locale-aware date formatting | | formatRelativeTime | (value, unit, locale) | Relative time e.g. "2 days ago" | | formatPercent | (value, locale, decimals?) | Locale-aware percent formatting | | formatUnit | (value, unit, locale) | Locale-aware unit formatting | | formatList | (items, locale, type?) | Locale-aware list formatting | | getPlural | (count, locale, forms) | Plural form selection via Intl.PluralRules | | compareStrings | (str1, str2, locale) | Locale-aware string comparison | | parseNumberWords | (text, locale) | Word to digit ("two" → 2), supports en-US/af-ZA | | handleBiDi | (text) | Wrap text in Unicode BiDi markers | | humanFileSize | (bytes) | Bytes to human-readable size | | getUUID | () | UUID via crypto.randomUUID() with timestamp fallback | | newUUID | () | UUID via uuid v4 | | blankValue | (...args) | First non-blank value (skips null/undefined/0/""/[]/{}) | | inop | (...args) | Check if value exists in array or matches value | | iinop | (...args) | Case-insensitive inop | | clarionIntToTime | (val, detail?) | Clarion int → time string HH:MM:SS | | clarionTimeToInt | (timeStr) | Time string → Clarion int | | clarionClock | () | Current time as Clarion centiseconds since midnight | | clarionDateToInt | (date) | JS Date → Clarion date int (days since 1800-12-28) | | clarionIntToDate | (days) | Clarion date int → JS Date | | clarionDateStringToInt | (dateStr) | "YYYY-MM-DD" or "MM/DD/YYYY" → Clarion int | | clarionIntToDateString | (days, format?) | Clarion int → date string, format: 'iso'|'us' | | fromBaseN | (str, base?) | String in base N (2-36) → BigInt, default base 36 | | toBaseN | (num, base?) | number|BigInt → string in base N (2-36), default base 36 | | tryFromBaseN | (str, base?, fallback?) | fromBaseN with fallback on error | | tryToBaseN | (num, base?, fallback?) | toBaseN with fallback on error |

Text helpers (strings)

These functions are exported from @warkypublic/artemis-kit/strings and the package root.

| Function | Behavior | |---|---| | truncate(text, maxLength, suffix = "…") | Limit total character count, including suffix; clip the suffix if necessary | | truncateWords(text, maxWords, suffix = "…") | Keep whitespace-delimited words; preserve original text if it fits | | slugify(text) | Lowercase, strip decomposable accents, join Unicode letters/numbers with hyphens | | escapeRegExp(text) | Escape regex metacharacters for a literal pattern | | normalizeWhitespace(text) | Collapse whitespace to spaces and trim | | stripDiacritics(text) | Remove decomposable accents and combining marks; not transliteration | | includesIgnoreCase(text, query, locale?) | Literal substring match after locale-aware lowercasing | | interpolate(template, values) | Replace {name} using own properties only; missing keys remain unchanged | | mask(text, options?) | Hide characters; defaults to showing the last four | | splitOnce(text, separator) | Return [before, after] at the first literal separator | | isBlank(text) | True for null, undefined, empty, or whitespace-only strings | | toSearchKey(text, locale?) | Lowercase, remove accents, and normalize whitespace | | humanize(text) | Turn identifiers such as customer_id or customerId into Customer id | | getInitials(name, max = 2) | Uppercase the first character of up to max whitespace-delimited words | | ensurePrefix(text, prefix) / ensureSuffix(text, suffix) | Add an exact affix only when absent | | removePrefix(text, prefix) / removeSuffix(text, suffix) | Remove an exact affix once | | substringBefore(text, separator) / substringAfter(text, separator) | Extract either side of the first literal separator | | countOccurrences(text, search, overlap = false) | Count literal matches; empty search returns zero | | commonPrefix(values) | Longest shared prefix; empty list returns an empty string | | wrapText(text, width) | Wrap at whitespace, preserve explicit line breaks, leave long words intact | | dedent(text) | Remove shared literal spaces/tabs and outer blank lines | | normalizeLineEndings(text) | Convert CRLF and CR to LF | | utf8ByteLength(text) | Count UTF-8 bytes, including replacement bytes for lone surrogates | | compareNatural(a, b) | Sort numeric text naturally using the runtime locale, with empty strings last |

import {
  truncate, toSearchKey, interpolate, mask, compareNatural,
} from "@warkypublic/artemis-kit/strings"

truncate("Hello world", 8) // "Hello w…"
toSearchKey("  CAFÉ  au lait ") // "cafe au lait"
interpolate("Hello {name}", { name: "Ada" }) // "Hello Ada"
mask("123456789", { start: 2, end: 2, character: "#" }) // "12#####89"
const files = ["file10", "file2"].sort(compareNatural) // ["file2", "file10"]

Character-based helpers use grapheme clusters when Intl.Segmenter is available, keeping combined emoji and accented characters together. Older runtimes fall back to Unicode code points, which keep surrogate pairs intact but may separate combined characters. Length limits must be nonnegative safe integers; wrapText requires a positive width. Invalid limits throw RangeError. A zero truncation limit returns an empty string.

mask accepts { start?: number, end?: number, character?: string }. The mask character must be one character; overlapping visible ranges leave the text visible. Masking changes only the displayed string. interpolate stringifies numbers and booleans, turns null/undefined values into empty strings, and does not evaluate or recursively substitute values. It does not escape HTML.

A missing separator yields [text, ""] from splitOnce; an empty separator yields ["", text]. The substring helpers follow the same rules. Affixes are case-sensitive and empty affixes leave text unchanged. includesIgnoreCase does not remove accents or perform full Unicode case folding; use toSearchKey on both operands for accent-insensitive search. wrapText collapses whitespace within lines; dedent treats tabs literally rather than expanding them to visual columns.

base64

import { ... } from "@warkypublic/artemis-kit/base64"

| Function | Signature | Description | |---|---|---| | b64EncodeUnicode | (str) | UTF-8 safe base64 encode | | b64DecodeUnicode | (str) | UTF-8 safe base64 decode | | base64ToBlob | (base64, mimeType) | Base64 string → Blob | | blobToBase64 | (blob) | Blob → base64 string | | FileToBase64 | (file) | File → base64 string | | FileToBlob | (file) | File → Blob | | BlobToString | (blob) | Blob → string |

object

import { ... } from "@warkypublic/artemis-kit/object"

| Function | Signature | Description | |---|---|---| | getNestedValue | (path, obj) | Get value by dot-notation path, supports bracket notation | | setNestedValue | (path, value, obj) | Set value by dot-notation path, auto-creates intermediates | | objectCompare | (obj, objToCompare, deep?) | Shallow or deep object equality | | createSelectOptions | (obj, options?) | Object → [{label, value}] array for select components | | decycle | (object, replacer?) | Deep copy, replacing circular refs with {"$ref": PATH} | | retrocycle | ($) | Restore circular refs from {"$ref": PATH} objects | | stringify_json | (object) | JSON.stringify safe for circular references |

Selecting and transforming properties

import {
  pick, omit, pickBy, omitBy, mapValues, mapKeys,
  isPlainObject, hasOwn, compactObject, invert,
} from "@warkypublic/artemis-kit/object"

const user = { id: 1, name: "Ada", password: "secret" }
pick(user, ["id", "name"]) // { id: 1, name: "Ada" }
omit(user, ["password"]) // { id: 1, name: "Ada" }
pickBy({ a: 1, b: 0 }, value => value > 0) // { a: 1 }
omitBy({ a: 1, b: 0 }, value => value > 0) // { b: 0 }
mapValues({ a: 2, b: 3 }, value => value * 2) // { a: 4, b: 6 }
mapKeys({ first: "Ada" }, key => key.toUpperCase()) // { FIRST: "Ada" }
isPlainObject({}) // true
isPlainObject(new Date()) // false
hasOwn({ id: 1 }, "id") // true
hasOwn({}, "toString") // false
compactObject({ a: null, b: undefined, c: 0, d: false, e: "" })
// { c: 0, d: false, e: "" }
invert({ a: "red", b: "red", c: "blue" })
// Map { "red" => ["a", "b"], "blue" => ["c"] }

These helpers produce shallow results and preserve value references. They operate on own enumerable string and symbol properties; pick can also select an explicitly named non-enumerable own property. Results contain ordinary writable data properties, not the original descriptors. Accessors are read when selected or transformed. mapKeys keeps the last value when mapped keys collide. invert groups duplicate values using Map equality, so object values are compared by identity. isPlainObject accepts objects with this realm's Object.prototype or a null prototype. Class instances and objects from another realm are not plain objects. Keys such as __proto__ are copied as own data properties without changing prototypes. Use these helpers on data records: static types cannot describe property enumeration or distinguish inherited keys from own keys.

Cloning, merging, and freezing

import { deepClone, deepMerge, deepFreeze } from "@warkypublic/artemis-kit/object"

const original = { user: { name: "Ada" }, created: new Date(0) }
const copy = deepClone(original)
copy.user === original.user // false
copy.created.getTime() // 0

const defaults = { theme: { color: "blue", size: 12 }, tags: ["base"] }
const overrides = { theme: { size: 14 }, tags: ["custom"] }
deepMerge(defaults, overrides)
// { theme: { color: "blue", size: 14 }, tags: ["custom"] }
deepMerge(defaults, overrides, { arrays: "concat" })
// { theme: { color: "blue", size: 14 }, tags: ["base", "custom"] }

const config = deepFreeze({ nested: { enabled: true }, tags: ["fixed"] })
Object.isFrozen(config.nested) // true
Object.isFrozen(config.tags) // true

deepClone preserves cycles and shared references. It supports primitives, plain objects, arrays, Date, RegExp (including lastIndex), Map, Set, ArrayBuffer, typed arrays, and DataView. Buffer views share the cloned backing buffer when the originals share one. Sparse array holes and null prototypes are preserved. Plain objects and arrays copy own enumerable string/symbol values; accessors become evaluated values. Custom properties on built-ins are not copied. Functions, custom classes, WeakMap, WeakSet, SharedArrayBuffer, and other unsupported objects throw TypeError.

deepMerge requires plain-object roots and returns a new object, leaving both inputs unchanged. Nested plain objects merge recursively; source values, including undefined, replace other values. Arrays are replaced unless arrays: "concat" is selected. Other values use deepClone's supported types. Cycles through traversed plain objects or arrays throw TypeError; shared identity across independently merged branches is not guaranteed. The result type is Record<PropertyKey, unknown> because overlapping values may have different types; narrow values before use.

deepFreeze freezes its input in place and returns it as DeepReadonly<T>. It supports cycles, plain objects, and arrays, including non-enumerable and symbol properties. Accessors, functions, and built-ins such as Date, Map, Set, and typed arrays throw TypeError before any part of the graph is frozen. This avoids implying that freezing an object also prevents mutation through built-in methods.

Flattening and changes

import { flattenObject, unflattenObject, diffObjects } from "@warkypublic/artemis-kit/object"

const flat = flattenObject({ user: { name: "Ada" }, tags: ["admin"], empty: {} })
// { "/user/name": "Ada", "/tags": ["admin"], "/empty": {} }
unflattenObject(flat)
// { user: { name: "Ada" }, tags: ["admin"], empty: {} }
flattenObject({ "a/b": { "~key": 1 } })
// { "/a~1b/~0key": 1 }

diffObjects({ user: { name: "Ada" }, old: true }, { user: { name: "Grace" }, active: true })
// [
//   { type: "changed", path: ["user", "name"], before: "Ada", after: "Grace" },
//   { type: "removed", path: ["old"], before: true },
//   { type: "added", path: ["active"], after: true },
// ]

Flattening traverses only nested plain objects with enumerable string keys. Paths start with /; key characters ~ and / become ~0 and ~1. Empty keys are supported ("/" is the path for an empty root key). Arrays, special objects, and empty objects are leaves and keep their original references. Empty roots produce {}. unflattenObject reconstructs plain objects without inferring arrays from numeric keys, and rejects invalid paths and parent/child collisions such as /a and /a/b. Symbol and non-enumerable properties are outside this representation.

diffObjects compares own enumerable string keys in plain objects recursively. Other values, including arrays and dates, use Object.is: distinct but equal-content arrays report a change. Added/removed subtrees are reported as a single entry; absence differs from an own property containing undefined. Paths are key arrays so punctuation in keys is unambiguous. Returned values retain input references. Flattening and diffing reject cycles through the plain objects they traverse.

TypeScript utility types

import type {
  DeepPartial, DeepReadonly, DeepRequired, Mutable, KeysOfType, Prettify,
} from "@warkypublic/artemis-kit/object"

type Settings = { name: string; nested: { enabled: boolean }; tags: string[] }
const patch: DeepPartial<Settings> = { nested: {} }
type FrozenSettings = DeepReadonly<Settings> // nested fields and arrays are readonly
const complete: DeepRequired<{ nested?: { enabled?: boolean } }> = {
  nested: { enabled: true },
}
type Editable = Mutable<{ readonly id: number }> // { id: number }
type TextKeys = KeysOfType<{ id: number; name: string }, string> // "name"
type User = Prettify<{ id: number } & { name: string }> // expanded editor display

DeepPartial and DeepRequired preserve tuple structure and recurse through object properties, map values, and set elements. Map keys are unchanged. DeepReadonly also makes map keys/values and set elements recursively readonly. These types preserve functions, Date, and RegExp as-is; they target data shapes, not arbitrary class instances. Readonly typing does not prevent mutation through Date/RegExp methods. Mutable removes only top-level readonly modifiers. KeysOfType selects properties whose entire declared value type extends the requested type. These are compile-time utilities, not runtime validation or freezing.

dataqueue

import { NestedQueue, EnhancedNestedQueue } from "@warkypublic/artemis-kit/dataqueue"

NestedQueue<T> — reactive array store with middleware and persistence.

| Method | Signature | Description | |---|---|---| | add | (item, path?) | Append item, optionally to nested array at path | | remove | (path) | Remove item at dot-notation index path | | update | (path, value) | Merge partial update at path | | get | (path) | Get value at path | | getAll | () | Get full data array | | search | (query, options?) | Search by string or object pattern | | filter | (predicate, options?) | Filter with optional deep traversal | | findOne | (predicate) | First matching item | | sort | (key, options?) | Sort by key, supports deep/nested sorting | | clear | () | Empty the queue | | subscribe | (callback) | Subscribe to changes, returns unsubscribe fn | | clearPersistence | () | Clear persistence adapter storage |

Constructor options:

new NestedQueue<T>(initialData?, {
  persistence?: PersistenceAdapter<T>,  // { save, load, clear }
  middleware?: Middleware<T>[],          // { beforeAction?, afterAction? }
  autoload?: boolean                     // auto-load from persistence on init
})

EnhancedNestedQueue<T> extends NestedQueue with an ActiveRecordBuffer — access via .getBuffer().

i18n

import { i18n, _t, _tt } from "@warkypublic/artemis-kit/i18n"

LRU memory cache + IndexedDB persistence, auto-fetches from server on miss/version mismatch.

| Export | Type | Description | |---|---|---| | _t | (id, default?) | Sync lookup (returns default if not cached) | | _tt | (id, default?) | Async lookup (fetches from server if missing) | | i18n.configure | (options) | Set apiUrl, maxCacheSize, cacheTTL | | i18n.registerStrings | (strings, version) | Pre-load translations | | i18n.clearCache | () | Clear memory + IndexedDB cache | | i18n.getCacheStats | () | { memorySize, dbSize, hits, misses } |

Configure:

i18n.configure({ apiUrl: "/api/translations", maxCacheSize: 1000, cacheTTL: 86400000 })

mime

import { ... } from "@warkypublic/artemis-kit/mime"

| Function | Signature | Description | |---|---|---| | getExtFromMime | (mime) | MIME type → primary extension | | getMimeFromExt | (ext) | Extension → MIME type | | getExtFromFilename | (filename) | Filename → extension | | isValidExtForMime | (mime, ext) | Validate extension against MIME type | | getAllExtensionsForMime | (mime) | All valid extensions for MIME type |

dom

import { openFileLink } from "@warkypublic/artemis-kit/dom"

| Function | Signature | Description | |---|---|---| | openFileLink | (url) | Trigger file download via hidden anchor click (browser only) |

promise

import { ... } from "@warkypublic/artemis-kit/promise"

| Function | Signature | Description | |---|---|---| | WaitUntil | (condition, options?) | Poll until condition returns true, throws on timeout | | debounce | (fn, wait) | Debounce function by ms | | throttle | (fn, limit) | Throttle function by ms | | measureTime | (fn) | Measure async fn execution: { result, duration } |

WaitUntil options: { timeout?: number (default 5000), interval?: number (default 100) }

logger

import { createLogger } from "@warkypublic/artemis-kit/logger"

const logger = createLogger()
logger.error(message, data?)
logger.warn(message, data?)
logger.info(message, data?)
logger.debug(message, data?)
logger.registerPlugin({ name, onLog: async (entry) => void })

Plugin entry: { timestamp: Date, level: 'ERROR'|'WARN'|'INFO'|'DEBUG', message: string, data?: unknown }

llm

import { OpenAPI, Claude } from "@warkypublic/artemis-kit/llm"

| Function | Signature | Description | |---|---|---| | OpenAPI.getTextCompletion | ({ prompt, options? }) | OpenAI-compatible text completion | | Claude.getClaudeCompletion | ({ prompt, options? }) | Anthropic Claude messages API completion |

OpenAPI options: { url?, apiKey?, maxTokens?, temperature?, topP?, n?, stream?, stop? }

Claude options: { url?, apiKey?, model?, maxTokens?, temperature?, topP?, stopSequences?, system? }

Installing from Gitea Packages

To install from Gitea, put this scope mapping in the consuming project's .npmrc, replacing <owner> with the Gitea repository owner:

@warkypublic:registry=https://git.warky.dev/api/packages/<owner>/npm/

Then run pnpm add @warkypublic/artemis-kit. For private packages, also configure an authentication token with package-read access in your user-level npm config or CI secrets. The scope mapping routes all @warkypublic packages to this registry.