@bessemer/cornerstone 0.5.0

package/jest.config.js

@@ -0,0 +1,3 @@
+import BaseConfig from '../jest.base.mjs'
+
+export default BaseConfig

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bessemer/cornerstone",
+  "type": "module",
+  "version": "0.5.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup && tsc --project tsconfig.build.json --emitDeclarationOnly",
+    "test": "jest",
+    "prettier-fix": "prettier --write .",
+    "clean": "rm -rf dist && rm -rf .turbo"
+  },
+  "dependencies": {
+    "date-fns": "4.1.0",
+    "immer": "10.1.1",
+    "lodash-es": "4.17.21",
+    "minimatch": "10.0.1",
+    "pino": "9.6.0",
+    "type-fest": "4.32.0",
+    "ulid": "2.3.0",
+    "zod": "3.24.2"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "4.17.12",
+    "pino-pretty": "13.0.0"
+  }
+}

package/src/array.ts

@@ -0,0 +1,142 @@
+import {
+  concat,
+  differenceBy as _differenceBy,
+  differenceWith as _differenceWith,
+  first as _first,
+  flatten as _flatten,
+  groupBy as _groupBy,
+  isEmpty as _isEmpty,
+  last as _last,
+  range as _range,
+  remove as _remove,
+  uniqBy,
+  uniqWith,
+} from 'lodash-es'
+import { Equalitor } from '@bessemer/cornerstone/equalitor'
+import { Signable } from '@bessemer/cornerstone/signature'
+import { Comparators, Eithers, Preconditions, Signatures } from '@bessemer/cornerstone'
+import { Either } from '@bessemer/cornerstone/either'
+import { Comparator } from '@bessemer/cornerstone/comparator'
+import { Arrayable } from 'type-fest'
+
+export const equalWith = <T>(first: Array<T>, second: Array<T>, equalitor: Equalitor<T>): boolean => {
+  if (first.length !== second.length) {
+    return false
+  }
+
+  return first.every((element, index) => equalitor(element, second[index]!))
+}
+
+export const equalBy = <T>(first: Array<T>, second: Array<T>, mapper: (element: T) => Signable): boolean => {
+  return equalWith(first, second, (first, second) => Signatures.sign(mapper(first)) === Signatures.sign(mapper(second)))
+}
+
+export const equal = <T extends Signable>(first: Array<T>, second: Array<T>): boolean => {
+  return equalBy(first, second, Signatures.sign)
+}
+
+export const differenceWith = <T>(first: Array<T>, second: Array<T>, equalitor: Equalitor<T>): Array<T> => {
+  return _differenceWith(first, second, equalitor)
+}
+
+export const differenceBy = <T>(first: Array<T>, second: Array<T>, mapper: (element: T) => Signable): Array<T> => {
+  return _differenceBy(first, second, (it) => Signatures.sign(mapper(it)))
+}
+
+export const difference = <T extends Signable>(first: Array<T>, second: Array<T>): Array<T> => {
+  return differenceBy(first, second, Signatures.sign)
+}
+
+export const removeWith = <T>(array: Array<T>, element: T, equalitor: Equalitor<T>): Array<T> => {
+  return differenceWith(array, [element], equalitor)
+}
+
+export const removeBy = <T>(array: Array<T>, element: T, mapper: (element: T) => Signable): Array<T> => {
+  return differenceBy(array, [element], mapper)
+}
+
+export const remove = <T extends Signable>(array: Array<T>, element: T): Array<T> => {
+  return difference(array, [element])
+}
+
+export const containsWith = <T>(array: Array<T>, element: T, equalitor: Equalitor<T>): boolean => {
+  return array.some((it) => equalitor(it, element))
+}
+
+export const containsBy = <T>(array: Array<T>, element: T, mapper: (element: T) => Signable): boolean => {
+  return containsWith(array, element, (first, second) => Signatures.sign(mapper(first)) === Signatures.sign(mapper(second)))
+}
+
+export const contains = <T extends Signable>(array: Array<T>, element: T): boolean => containsBy(array, element, Signatures.sign)
+
+export const containsAllWith = <T>(first: Array<T>, second: Array<T>, equalitor: Equalitor<T>): boolean =>
+  isEmpty(differenceWith(second, first, equalitor))
+
+export const containsAllBy = <T>(first: Array<T>, second: Array<T>, mapper: (element: T) => Signable): boolean =>
+  isEmpty(differenceBy(second, first, mapper))
+
+export const containsAll = <T extends Signable>(first: Array<T>, second: Array<T>): boolean => isEmpty(difference(second, first))
+
+export const dedupeWith = <T>(array: Array<T>, equalitor: Equalitor<T>): Array<T> => {
+  return uniqWith(array, equalitor)
+}
+
+export const dedupeBy = <T>(array: Array<T>, mapper: (element: T) => Signable): Array<T> => {
+  return uniqBy(array, (it) => Signatures.sign(mapper(it)))
+}
+
+export const dedupe = <T extends Signable>(array: Array<T>): Array<T> => {
+  return dedupeBy(array, Signatures.sign)
+}
+
+export const sortWith = <T>(array: Array<T>, comparator: Comparator<T>): Array<T> => {
+  return [...array].sort(comparator)
+}
+
+export const sortBy = <T>(array: Array<T>, mapper: (element: T) => Signable): Array<T> => {
+  return sortWith(
+    array,
+    Comparators.compareBy((it) => Signatures.sign(mapper(it)), Comparators.natural())
+  )
+}
+
+export const sort = <T extends Signable>(array: Array<T>): Array<T> => sortBy(array, Signatures.sign)
+
+export const concatenate = concat
+
+export const first = _first
+
+export const only = <T>(array: Array<T>): T => {
+  Preconditions.isTrue(array.length === 1)
+  return first(array)!
+}
+
+export const last = _last
+
+export const isEmpty = _isEmpty
+// TODO make a better range function
+export const range = _range
+// TODO should this live in collections?
+export const groupBy = _groupBy
+
+export const rest = <T>(array: Array<T>, elementsToSkip: number = 1): Array<T> => {
+  return array.slice(elementsToSkip)
+}
+
+export const clear = (array: Array<unknown>): void => {
+  _remove(array, () => true)
+}
+
+export const bisect = <T, L, R>(array: Array<T>, bisector: (element: T, index: number) => Either<L, R>): [Array<L>, Array<R>] => {
+  return Eithers.split(array.map(bisector))
+}
+
+export const toArray = <T>(array: Arrayable<T>): Array<T> => {
+  if (Array.isArray(array)) {
+    return array
+  }
+
+  return [array]
+}
+
+export const flatten = _flatten

package/src/async.ts

@@ -0,0 +1,114 @@
+import { Duration } from '@bessemer/cornerstone/duration'
+import { Durations, Objects } from '@bessemer/cornerstone'
+
+export type PendingValue = {
+  isSuccess: false
+  isError: false
+  isLoading: false
+  isFetching: boolean
+  data: undefined
+}
+
+export type LoadingValue = {
+  isSuccess: false
+  isError: false
+  isLoading: true
+  isFetching: boolean
+  data: undefined
+}
+
+export type ErrorValue = {
+  isSuccess: false
+  isError: true
+  isLoading: false
+  isFetching: boolean
+  data: unknown
+}
+
+export type FetchingValueSuccess<T> = {
+  isSuccess: true
+  isError: false
+  isLoading: false
+  isFetching: true
+  data: T
+}
+
+export type FetchingValueError = {
+  isSuccess: false
+  isError: true
+  isLoading: false
+  isFetching: true
+  data: unknown
+}
+
+export type SettledValue<T> = {
+  isSuccess: true
+  isError: false
+  isLoading: false
+  isFetching: false
+  data: T
+}
+
+export type AsyncValue<T> = PendingValue | LoadingValue | ErrorValue | FetchingValueSuccess<T> | FetchingValueError | SettledValue<T>
+
+export const isSettled = <T>(value: AsyncValue<T>): value is SettledValue<T> => {
+  return value.isSuccess && !value.isError && !value.isLoading && !value.isFetching
+}
+
+export const loading = (): LoadingValue => ({ isSuccess: false, isError: false, isLoading: true, isFetching: true, data: undefined })
+
+export const fetching = <T>(data: T): FetchingValueSuccess<T> => ({
+  isSuccess: true,
+  isError: false,
+  isLoading: false,
+  isFetching: true,
+  data,
+})
+
+export const settled = <T>(data: T): SettledValue<T> => ({ isSuccess: true, isError: false, isLoading: false, isFetching: false, data })
+
+export const error = (error: unknown): ErrorValue => ({ isSuccess: false, isError: true, isLoading: false, isFetching: false, data: error })
+
+export const handle = <T, N>(
+  value: AsyncValue<T | null>,
+  handlers: { loading: () => N; error: (error: unknown) => N; absent: () => N; success: (data: T) => N }
+): N => {
+  if (value.isLoading || (value.isError && value.isFetching)) {
+    return handlers.loading()
+  }
+  if (value.isError) {
+    return handlers.error(value.data)
+  }
+  if (Objects.isNil(value.data)) {
+    return handlers.absent()
+  }
+
+  return handlers.success(value.data)
+}
+
+export const map = <T, N>(value: AsyncValue<T>, mapper: (value: T) => N): AsyncValue<N> => {
+  if (!value.isSuccess) {
+    return value
+  }
+
+  return { ...value, data: mapper(value.data) }
+}
+
+export const execute = <T>(runnable: () => Promise<T>): Promise<T> => {
+  return new Promise(async (resolve, reject) => {
+    setTimeout(async () => {
+      try {
+        const value = await runnable()
+        resolve(value)
+      } catch (e) {
+        reject(e)
+      }
+    }, 0)
+  })
+}
+
+export const sleep = (duration: Duration): Promise<void> => {
+  return new Promise((resolve) => {
+    setTimeout(resolve, Durations.inMilliseconds(duration))
+  })
+}

package/src/cache.ts

@@ -0,0 +1,236 @@
+import { AbstractLocalKeyValueStore, AbstractRemoteKeyValueStore, LocalKeyValueStore, RemoteKeyValueStore } from '@bessemer/cornerstone/store'
+import { Arrays, Dates, Durations, Objects, Strings, Zod } from '@bessemer/cornerstone'
+import { Duration } from '@bessemer/cornerstone/duration'
+import { ResourceKey, ResourceNamespace } from '@bessemer/cornerstone/resource'
+import { AbstractApplicationContext } from '@bessemer/cornerstone/context'
+import { NominalType } from '@bessemer/cornerstone/types'
+import { Entry } from '@bessemer/cornerstone/entry'
+import { GlobPattern } from '@bessemer/cornerstone/glob'
+import { Arrayable } from 'type-fest'
+import { ZodType } from 'zod'
+
+// JOHN should this even be in cornerstone? especially consider the config types down at the bottom
+
+export type CacheProps = {
+  maxSize: number | null
+  timeToLive: Duration
+  timeToStale: Duration | null
+}
+
+export type CacheOptions = Partial<CacheProps>
+
+export namespace CacheProps {
+  const DefaultCacheProps = {
+    maxSize: 50000,
+    timeToLive: Durations.OneDay,
+    timeToStale: Durations.OneHour,
+  }
+
+  export const buildCacheProps = (options?: CacheOptions): CacheProps => {
+    options = options ?? {}
+
+    const props = Objects.merge(DefaultCacheProps, options)
+
+    if (props.maxSize === null && props.timeToLive === null) {
+      throw new Error('Invalid cache configuration, both maxSize and timeToLive are null')
+    }
+
+    return props
+  }
+}
+
+export namespace CacheKey {
+  // We use a hardcoded UUID to represent a unique token value that serves as a flag to disable caching
+  const DisableCacheToken = 'f6822c1a-d527-4c65-b9dd-ddc24620b684'
+
+  export const disableCaching = (): ResourceNamespace => {
+    return DisableCacheToken
+  }
+
+  export const isDisabled = (key: ResourceNamespace): boolean => {
+    return Strings.contains(key, DisableCacheToken)
+  }
+}
+
+export type CacheSector = {
+  globs: Array<GlobPattern>
+}
+
+export namespace CacheSector {
+  export const of = (globs: Arrayable<GlobPattern>) => {
+    return { globs: Arrays.toArray(globs) }
+  }
+
+  export const namespace = (namespace: ResourceNamespace, sector: CacheSector): CacheSector => {
+    return { globs: ResourceKey.namespaceAll(namespace, sector.globs) }
+  }
+}
+
+export type CacheName = NominalType<string, 'CacheName'>
+export const CacheNameSchema: ZodType<CacheName> = Zod.string()
+
+export interface AbstractCache<T> {
+  name: CacheName
+}
+
+export interface Cache<T> extends AbstractCache<T> {
+  fetchValue(namespace: ResourceNamespace, key: ResourceKey, fetch: () => Promise<T>): Promise<T>
+
+  fetchValues(
+    namespace: ResourceNamespace,
+    keys: Array<ResourceKey>,
+    fetch: (keys: Array<ResourceKey>) => Promise<Array<Entry<T>>>
+  ): Promise<Array<Entry<T>>>
+
+  writeValue(namespace: ResourceNamespace, key: ResourceKey, value: T | undefined): Promise<void>
+
+  writeValues(namespace: ResourceNamespace, entries: Array<Entry<T | undefined>>): Promise<void>
+
+  evictAll(sector: CacheSector): Promise<void>
+}
+
+export interface CacheProvider<T> extends RemoteKeyValueStore<CacheEntry<T>> {
+  type: CacheProviderType
+
+  evictAll(sector: CacheSector): Promise<void>
+}
+
+export abstract class AbstractCacheProvider<T> extends AbstractRemoteKeyValueStore<CacheEntry<T>> implements CacheProvider<T> {
+  abstract type: CacheProviderType
+
+  abstract evictAll(sector: CacheSector): Promise<void>
+}
+
+export interface LocalCache<T> extends AbstractCache<T> {
+  getValue(namespace: ResourceNamespace, key: ResourceKey, fetch: () => T): T
+
+  getValues(namespace: ResourceNamespace, keys: Array<ResourceKey>, fetch: (keys: Array<ResourceKey>) => Array<Entry<T>>): Array<Entry<T>>
+
+  setValue(namespace: ResourceNamespace, key: ResourceKey, value: T | undefined): void
+
+  setValues(namespace: ResourceNamespace, entries: Array<Entry<T | undefined>>): void
+
+  removeAll(sector: CacheSector): void
+}
+
+export interface LocalCacheProvider<T> extends LocalKeyValueStore<CacheEntry<T>>, CacheProvider<T> {
+  removeAll(sector: CacheSector): void
+}
+
+export abstract class AbstractLocalCacheProvider<T> extends AbstractLocalKeyValueStore<CacheEntry<T>> implements LocalCacheProvider<T> {
+  abstract type: CacheProviderType
+
+  abstract removeAll(sector: CacheSector): void
+
+  async evictAll(sector: CacheSector): Promise<void> {
+    this.removeAll(sector)
+  }
+}
+
+export type CacheEntry<T> = {
+  value: T
+  liveTimestamp: Date | null
+  staleTimestamp: Date | null
+}
+
+export namespace CacheEntry {
+  export const isActive = <T>(entry: CacheEntry<T>): boolean => {
+    if (isDead(entry) || isStale(entry)) {
+      return false
+    }
+
+    return true
+  }
+
+  export const isDead = <T>(entry: CacheEntry<T> | undefined): boolean => {
+    if (Objects.isNil(entry)) {
+      return true
+    }
+
+    if (Objects.isNil(entry.liveTimestamp)) {
+      return false
+    }
+
+    return Dates.isBefore(entry.liveTimestamp, Dates.now())
+  }
+
+  export const isAlive = <T>(entry: CacheEntry<T> | undefined): boolean => !isDead(entry)
+
+  export const isStale = <T>(entry: CacheEntry<T>): boolean => {
+    if (Objects.isNil(entry.staleTimestamp)) {
+      return false
+    }
+
+    return Dates.isBefore(entry.staleTimestamp, Dates.now())
+  }
+
+  export const of = <T>(value: T) => {
+    const entry: CacheEntry<T> = {
+      value,
+      liveTimestamp: null,
+      staleTimestamp: null,
+    }
+
+    return entry
+  }
+
+  // JOHN do we want to enforce some kind of minimum liveness threshold?
+  export const applyProps = <T>(originalEntry: CacheEntry<T>, props: CacheProps): CacheEntry<T> => {
+    let liveTimestamp: Date | null = originalEntry.liveTimestamp
+    if (!Objects.isNil(props.timeToLive)) {
+      const limit = Dates.addMilliseconds(Dates.now(), Durations.inMilliseconds(props.timeToLive))
+      if (Dates.isBefore(limit, liveTimestamp ?? limit)) {
+        liveTimestamp = limit
+      }
+    }
+
+    let staleTimestamp: Date | null = originalEntry.staleTimestamp
+    if (!Objects.isNil(props.timeToStale)) {
+      const limit = Dates.addMilliseconds(Dates.now(), Durations.inMilliseconds(props.timeToStale))
+      if (Dates.isBefore(limit, staleTimestamp ?? limit)) {
+        staleTimestamp = limit
+      }
+    }
+
+    const limitedEntry: CacheEntry<T> = {
+      value: originalEntry.value,
+      liveTimestamp,
+      staleTimestamp,
+    }
+
+    return limitedEntry
+  }
+}
+
+export type CacheConfigurationOptions = CacheConfigurationSection & {
+  local: CacheConfigurationSection
+}
+
+export type CacheConfigurationSection = {
+  defaults: CacheDefinition
+
+  /**
+   * These options map from cache name key to configuration. They are a way for the tenant to override the configurations
+   * for specific caches from the cache configuration here.
+   */
+  caches?: Record<string, Partial<CacheDefinition>>
+}
+
+export type CacheDefinition = {
+  options?: CacheOptions
+  providers: Array<CacheProviderConfiguration>
+}
+
+export type CacheProviderType = NominalType<string, 'CacheProviderType'>
+export type CacheProviderConfiguration = CacheOptions & {
+  type: CacheProviderType
+}
+
+export type CacheConfiguration = CacheConfigurationSection & {
+  local: CacheConfigurationSection
+}
+
+export type CacheProviderRegistry<ContextType extends AbstractApplicationContext> = {
+  type: CacheProviderType
+  construct: <T>(props: CacheProps, context: ContextType) => CacheProvider<T>
+}

package/src/combinable.ts

@@ -0,0 +1,40 @@
+import { Arrays, Sets } from '@bessemer/cornerstone'
+
+export interface Combinable {
+  combinability: Combinability
+}
+
+export type Combinability = {
+  type: CombinabilityType
+  class: CombinabilityClass
+}
+
+export enum CombinabilityType {
+  Stackable = 'Stackable',
+  Singleton = 'Singleton',
+  Totalitarian = 'Totalitarian',
+}
+
+export type CombinabilityClass = string | null
+
+export const DefaultCombinability: Combinability = {
+  type: CombinabilityType.Stackable,
+  class: null,
+}
+
+export const combinations = <T extends Combinable>(combinables: Array<T>): Array<Array<T>> => {
+  const classMap = Arrays.groupBy(combinables, (it) => it.combinability.class)
+
+  const classCombinations: Array<Array<Array<T>>> = Object.entries(classMap).map(([_, values]) => {
+    const totalitarianCombinations = values.filter((it) => it.combinability.type === CombinabilityType.Totalitarian).map((it) => [it])
+    if (!Arrays.isEmpty(totalitarianCombinations)) {
+      return totalitarianCombinations
+    }
+
+    const singletonCombinations = values.filter((it) => it.combinability.type === CombinabilityType.Singleton).map((it) => [it])
+    const stackableCombination = values.filter((it) => it.combinability.type === CombinabilityType.Stackable)
+    return [stackableCombination, ...singletonCombinations]
+  })
+
+  return Sets.cartesianProduct(...classCombinations).flatMap((it) => it)
+}

package/src/comparator.ts

@@ -0,0 +1,78 @@
+import { Maths, Strings } from '@bessemer/cornerstone'
+
+export type Comparator<T> = (first: T, second: T) => number
+
+export const aggregate = <T>(comparators: Array<Comparator<T>>): Comparator<T> => {
+  return (first, second) => {
+    if (first === second) {
+      return 0
+    }
+
+    for (const comparator of comparators) {
+      const result = comparator(first, second)
+      if (result !== 0) {
+        return result
+      }
+    }
+
+    return 0
+  }
+}
+
+export const compareBy = <T, N>(mapper: (element: T) => N, comparator: Comparator<N>): Comparator<T> => {
+  return (first, second) => comparator(mapper(first), mapper(second))
+}
+
+export const reverse = <T>(comparator: Comparator<T>): Comparator<T> => {
+  return (first, second) => -comparator(first, second)
+}
+
+export const trueFirst = (): Comparator<boolean> => {
+  return (first, second) => natural()(first ? 1 : 0, second ? 1 : 0)
+}
+
+export const natural = (): Comparator<string | number | null> => {
+  // Comparing by nulls first allows us to assume the elements are non-null for future comparisons
+  return aggregate([
+    nullsLast(),
+    (first, second) => {
+      if (Strings.isString(first) && Strings.isString(second)) {
+        return first.localeCompare(second)
+      } else if (Maths.isNumber(first) && Maths.isNumber(second)) {
+        return first! - second!
+      } else if (Maths.isNumber(first)) {
+        return -1
+      } else {
+        return 1
+      }
+    },
+  ])
+}
+
+export function matchedFirst<T>(target: T): Comparator<T | null> {
+  return aggregate([
+    nullsLast(),
+    (first, second) => {
+      if (first === target && second !== target) {
+        return -1
+      } else if (first !== target && second === target) {
+        return 1
+      } else {
+        return 0
+      }
+    },
+  ])
+}
+
+export const nullsLast = <T>(): Comparator<T> => {
+  return (first, second) => {
+    if (first === null) {
+      return 1
+    }
+    if (second === null) {
+      return -1
+    }
+
+    return 0
+  }
+}