artemis-kit/README.md

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

---

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

---

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.