@tstdl/base 0.93.36 → 0.93.38

package/source/orm/sqls.ts

@@ -1,374 +0,0 @@
-/**
- * @module
- * Provides utility SQL functions and constants for use with Drizzle ORM,
- * simplifying common SQL operations like generating UUIDs, working with intervals,
- * and aggregating data.
- */
-import { isDefined, isNumber, isString } from '#/utils/type-guards.js';
-import { sql, Table, type AnyColumn, type Column, type SQL, type SQLChunk } from 'drizzle-orm';
-import type { GetSelectTableSelection, SelectResultField, TableLike } from 'drizzle-orm/query-builders/select.types';
-import type { TsVectorWeight } from './query/index.js';
-import type { Uuid } from './types.js';
-
-/** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
-export const TRANSACTION_TIMESTAMP = sql<Date>`transaction_timestamp()`;
-
-/** Drizzle SQL helper for generating a random UUID (v4). Returns a Uuid string. */
-export const RANDOM_UUID_V4 = sql<Uuid>`gen_random_uuid()`;
-
-/** Drizzle SQL helper for generating a random UUID (v7). Returns a Uuid string. */
-export const RANDOM_UUID_V7 = sql<Uuid>`uuidv7()`;
-
-/** Represents valid units for PostgreSQL interval values. */
-export type IntervalUnit =
-  | 'millennium' | 'millenniums' | 'millennia'
-  | 'century' | 'centuries'
-  | 'decade' | 'decades'
-  | 'year' | 'years'
-  | 'day' | 'days'
-  | 'hour' | 'hours'
-  | 'minute' | 'minutes'
-  | 'second' | 'seconds'
-  | 'millisecond' | 'milliseconds'
-  | 'microsecond' | 'microseconds';
-
-export type TsHeadlineOptions = {
-  /**
-   * The longest headline to output.
-   * @default 35
-   */
-  maxWords?: number,
-
-  /**
-   * The shortest headline to output.
-   * @default 15
-   */
-  minWords?: number,
-
-  /**
-   * Words of this length or less will be dropped at the start and end of a headline, unless they are query terms.
-   * @default 3
-   */
-  shortWord?: number,
-
-  /**
-   * If true the whole document will be used as the headline, ignoring the preceding three parameters.
-   * @default false
-   */
-  highlightAll?: boolean,
-
-  /**
-   * Maximum number of text fragments to display. Default is 0, which selects a non-fragment-based headline generation method. A value greater than zero selects fragment-based headline generation.
-   * @default 0
-   */
-  maxFragments?: number,
-
-  /**
-   * The strings with which to delimit query words appearing in the document, to distinguish them from other excerpted words.
-   * @default '<b>'
-   */
-  startSel?: string,
-
-  /**
-   * The strings with which to delimit query words appearing in the document, to distinguish them from other excerpted words.
-   * @default '</b>'
-   */
-  stopSel?: string,
-
-  /**
-   * When more than one fragment is displayed, the fragments will be separated by this string.
-   * @default ' ... '
-   */
-  fragmentDelimiter?: string,
-};
-
-export function array<T>(values: SQL<T>[]): SQL<T[]>;
-export function array<T = unknown>(values: SQLChunk[]): SQL<T[]>;
-export function array(values: SQLChunk[]): SQL<unknown[]> {
-  const valueString = sql.join(values, sql.raw(', '));
-  return sql`ARRAY[${valueString}]`;
-}
-
-export function autoAlias<T>(column: AnyColumn<{ data: T }>): SQL.Aliased<T> {
-  return sql<T>`${column}`.as(`${(column.table as any)[(Table as any)['Symbol']['Name']]}_${column.name}`);
-}
-
-/**
- * Creates a PostgreSQL interval expression.
- * @param value - The numeric value of the interval.
- * @param unit - The unit of the interval (e.g., 'day', 'hour').
- * @returns A Drizzle SQL object representing the interval.
- */
-export function interval(value: number, unit: IntervalUnit): SQL {
-  return sql`(${value} ||' ${sql.raw(unit)}')::interval`;
-}
-
-/**
- * Creates a PostgreSQL `array_agg` aggregate function call.
- * Aggregates values from a column into a PostgreSQL array.
- * @template T - The Drizzle column type.
- * @param column - The column to aggregate.
- * @returns A Drizzle SQL object representing the aggregated array.
- */
-export function arrayAgg<T extends Column>(column: T): SQL<SelectResultField<T>[]> {
-  return sql`array_agg(${column})`;
-}
-
-/**
- * Creates a PostgreSQL `json_agg` aggregate function call.
- * Aggregates rows or column values into a JSON array.
- * @template T - The Drizzle table or column type.
- * @param tableOrColumn - The table or column to aggregate into JSON.
- * @returns A Drizzle SQL object representing the JSON aggregated array.
- */
-export function jsonAgg<T extends TableLike>(tableOrColumn: T): SQL<SelectResultField<GetSelectTableSelection<T>>[]> {
-  return sql`json_agg(${tableOrColumn})`;
-}
-
-/**
- * Variant of `jsonAgg` that includes null values in the resulting JSON array.
- * @template T - The Drizzle table or column type.
- * @param tableOrColumn - The table or column to aggregate into JSON.
- * @returns A Drizzle SQL object representing the JSON aggregated array, potentially containing nulls.
- */
-jsonAgg.withNull = (jsonAgg as <T extends TableLike>(tableOrColumn: T) => SQL<(SelectResultField<GetSelectTableSelection<T>> | null)[]>);
-
-/**
- * Creates a PostgreSQL `coalesce` function call.
- * Returns the first non-null value from the provided list of columns or SQL expressions.
- * @template T - An array type of Drizzle Columns or SQL expressions.
- * @param columns - The columns or SQL expressions to check.
- * @returns A Drizzle SQL object representing the coalesced value.
- */
-export function coalesce<T extends (Column | SQL)[]>(...columns: T): SQL<SelectResultField<T>[number]> {
-  return sql`coalesce(${sql.join(columns, sql.raw(', '))})`;
-}
-
-/**
- * Creates a PostgreSQL `to_jsonb` function call.
- * Converts the input column or SQL expression to a JSONB value.
- * @template T - The Drizzle column or SQL expression type.
- * @param column - The column or SQL expression to convert.
- * @returns A Drizzle SQL object representing the value as JSONB.
- */
-export function toJsonb<T extends (Column | SQL)>(column: T): SQL<SelectResultField<T>> {
-  return sql`to_jsonb(${column})`;
-}
-
-/**
- * Creates a PostgreSQL `num_nulls` function call.
- * Counts the number of null arguments.
- * @param columns - The columns to check for nulls.
- * @returns A Drizzle SQL object representing the count of nulls.
- */
-export function numNulls(...columns: Column[]): SQL<number> {
-  return sql`num_nulls(${sql.join(columns, sql.raw(', '))})`;
-}
-
-/**
- * Creates a PostgreSQL `num_nonnulls` function call.
- * Counts the number of non-null arguments.
- * @param columns - The columns to check for non-nulls.
- * @returns A Drizzle SQL object representing the count of non-nulls.
- */
-export function numNonNulls(...columns: Column[]): SQL<number> {
-  return sql`num_nonnulls(${sql.join(columns, sql.raw(', '))})`;
-}
-
-export function least<T extends (Column | SQL | number)[]>(...values: T): SQL<SelectResultField<{ [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P] }[number]>>;
-export function least<T>(...values: T[]): SQL<SelectResultField<T>>;
-export function least<T extends (Column | SQL | number)[]>(...values: T): SQL<SelectResultField<{ [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P] }[number]>> {
-  const sqlValues = values.map((value) => isNumber(value) ? sql.raw(String(value)) : value);
-  return sql`least(${sql.join(sqlValues, sql.raw(', '))})`;
-}
-
-export function greatest<T extends (Column | SQL | number)[]>(...values: T): SQL<SelectResultField<{ [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P] }[number]>>;
-export function greatest<T>(...values: T[]): SQL<SelectResultField<T>>;
-export function greatest<T extends (Column | SQL | number)[]>(...values: T): SQL<SelectResultField<{ [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P] }[number]>> {
-  const sqlValues = values.map((value) => isNumber(value) ? sql.raw(String(value)) : value);
-  return sql`greatest(${sql.join(sqlValues, sql.raw(', '))})`;
-}
-
-export function unnest<T>(array: SQL<readonly T[]>): SQL<T> {
-  return sql`unnest(${array})`;
-}
-
-export function toTsVector(language: string | SQLChunk, text: string | SQLChunk): SQL<string> {
-  return sql`to_tsvector(${language}, ${text})`;
-}
-
-export function tsvectorToArray(tsvector: SQL): SQL<string[]> {
-  return sql`tsvector_to_array(${tsvector})`;
-}
-
-/**
- * Creates a PostgreSQL `to_tsquery` function call.
- * This function parses text into a tsquery, respecting operators like & (AND), | (OR), and ! (NOT).
- * @param language The text search configuration (e.g., 'english').
- * @param text The search query text with operators.
- * @returns A Drizzle SQL object representing the tsquery.
- */
-export function toTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL {
-  return sql`to_tsquery(${language}, ${text})`;
-}
-
-/**
- * Creates a PostgreSQL `plainto_tsquery` function call.
- * This function parses text into tokens and normalizes them, creating a tsquery
- * where tokens are joined by the AND operator. It's useful for raw user input.
- * @param language The text search configuration (e.g., 'english').
- * @param text The search query text.
- * @returns A Drizzle SQL object representing the tsquery.
- */
-export function plainToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL {
-  return sql`plainto_tsquery(${language}, ${text})`;
-}
-
-/**
- * Creates a PostgreSQL `phraseto_tsquery` function call.
- * This function is similar to `plainto_tsquery` but creates a tsquery that searches for a phrase.
- * @param language The text search configuration (e.g., 'english').
- * @param text The phrase to search for.
- * @returns A Drizzle SQL object representing the tsquery.
- */
-export function phraseToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL {
-  return sql`phraseto_tsquery(${language}, ${text})`;
-}
-
-/**
- * Creates a PostgreSQL `websearch_to_tsquery` function call.
- * This function is similar to `plainto_tsquery` but also handles "quoted phrases"
- * and prefixes terms with `-` or `!` for negation. It's suitable for web search style inputs.
- * @param language The text search configuration (e.g., 'english').
- * @param text The search query text.
- * @returns A Drizzle SQL object representing the tsquery.
- */
-export function websearchToTsQuery(language: string | SQLChunk, text: string | SQLChunk): SQL {
-  return sql`websearch_to_tsquery(${language}, ${text})`;
-}
-
-/**
- * Creates a PostgreSQL `setweight` function call.
- * Assigns a weight ('A', 'B', 'C', 'D') to a tsvector.
- * @param tsvector The tsvector to weight.
- * @param weight The weight to assign.
- * @returns A Drizzle SQL object representing the weighted tsvector.
- */
-export function setweight(tsvector: SQL, weight: TsVectorWeight): SQL {
-  return sql`setweight(${tsvector}, '${sql.raw(weight)}')`;
-}
-
-/**
- * Creates a PostgreSQL `ts_rank_cd` function call for relevance ranking.
- * @param tsvector The document's tsvector.
- * @param tsquery The search query's tsquery.
- * @param options Optional configuration for ranking, including weights and normalization.
- * @returns A Drizzle SQL object representing the relevance score.
- */
-export function tsRankCd(tsvector: SQL, tsquery: SQL, options?: { weights?: number[], normalization?: number }): SQL<number> {
-  const parameters: (SQL | SQLChunk)[] = [];
-
-  if (isDefined(options?.weights)) {
-    const weightParts = options.weights.map((w) => sql.raw(String(w)));
-    parameters.push(sql`${array(weightParts)}::real[]`);
-  }
-
-  parameters.push(tsvector, tsquery);
-
-  if (isDefined(options?.normalization)) {
-    parameters.push(sql`${options.normalization}`);
-  }
-
-  return sql<number>`ts_rank_cd(${sql.join(parameters, sql.raw(', '))})`;
-}
-
-/**
- * Creates a PostgreSQL `ts_headline` function call for highlighting search results.
- *
- * @param language The text search configuration.
- * @param document The original text column.
- * @param tsquery The search query's tsquery.
- * @param options Optional configuration object for ts_headline (e.g., { MaxWords: 10 }).
- * @returns A Drizzle SQL object representing the highlighted text snippet.
- *
- * @warning If using HTML tags for `startSel` and `stopSel` (the default), be aware of
- * Cross-Site Scripting (XSS) vulnerabilities. Ensure the `document` content is
- * properly sanitized before rendering it in a browser if it comes from an untrusted source.
- */
-export function tsHeadline(language: string | SQLChunk, document: string | SQLChunk, tsquery: SQL, options?: TsHeadlineOptions): SQL<string> {
-  const documentSql = isString(document) ? sql`${document}` : document;
-
-  if (isDefined(options)) {
-    const optionsString = Object.entries(options).map(([key, value]) => `${key[0]!.toUpperCase()}${key.slice(1)}=${String(value)}`).join(', ');
-    return sql<string>`ts_headline(${language}, ${documentSql}, ${tsquery}, '${sql.raw(optionsString)}')`;
-  }
-
-  return sql<string>`ts_headline(${language}, ${documentSql}, ${tsquery})`;
-}
-
-/**
- * Creates a PostgreSQL `similarity` function call (from pg_trgm extension).
- * Calculates the similarity between two strings based on trigram matching.
- * @param left The first text column or expression.
- * @param right The second text value or expression to compare against.
- * @returns A Drizzle SQL object representing the similarity score (0 to 1).
- */
-export function similarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`similarity(${left}, ${right})`;
-}
-
-/**
- * Creates a PostgreSQL `word_similarity` function call (from pg_trgm extension).
- * Calculates the greatest similarity between the set of trigrams in the first string and any continuous extent of an ordered set of trigrams in the second string.
- * @param left The first text column or expression.
- * @param right The second text value or expression to compare against.
- * @returns A Drizzle SQL object representing the similarity score (0 to 1).
- */
-export function wordSimilarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`word_similarity(${left}, ${right})`;
-}
-
-/**
- * Creates a PostgreSQL `strict_word_similarity` function call (from pg_trgm extension).
- * Same as `word_similarity`, but forces extent boundaries to match word boundaries.
- * @param left The first text column or expression.
- * @param right The second text value or expression to compare against.
- * @returns A Drizzle SQL object representing the similarity score (0 to 1).
- */
-export function strictWordSimilarity(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`strict_word_similarity(${left}, ${right})`;
-}
-
-export function isSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean> {
-  return sql<boolean>`(${left} % ${right})`;
-}
-
-export function isWordSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean> {
-  return sql<boolean>`(${left} <% ${right})`;
-}
-
-export function isStrictWordSimilar(left: string | SQLChunk, right: string | SQLChunk): SQL<boolean> {
-  return sql<boolean>`(${left} <<% ${right})`;
-}
-
-export function distance(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`(${left} <-> ${right})`;
-}
-
-export function wordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`(${left} <<-> ${right})`;
-}
-
-export function strictWordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number> {
-  return sql<number>`(${left} <<<-> ${right})`;
-}
-
-export function jsonbBuildObject(properties: Record<string, any> | [string, any][]): SQL {
-  const entries = Array.isArray(properties) ? properties : Object.entries(properties);
-
-  const chunks = entries
-    .filter(([_, propValue]) => isDefined(propValue))
-    .map(([propKey, propValue]) => sql`'${sql.raw(propKey)}', ${propValue}`);
-
-  return sql`jsonb_build_object(${sql.join(chunks, sql`, `)})`;
-}

package/source/orm/types.ts

@@ -1,118 +0,0 @@
-/**
- * @module
- * Defines core ORM types, including tagged types for representing database column types
- * (like Uuid, Timestamp, Json, etc.) and helper types for working with Drizzle ORM features
- * like primary keys and default values. It also re-exports common decorators and schemas.
- */
-import type { $Type, HasDefault as DrizzleHasDefault, IsPrimaryKey as DrizzleIsPrimaryKey } from 'drizzle-orm';
-import type { boolean, doublePrecision, integer, jsonb, numeric, PgColumnBuilder, PgColumnBuilderBase, PgEnumColumnBuilderInitial, text, uuid } from 'drizzle-orm/pg-core';
-
-import type { AbstractConstructor, EnumerationObject, EnumerationValue, GetTagMetadata, HasTag, ObjectLiteral, Tagged, UnionToTuple, UnwrapTagged } from '#/types/index.js';
-import type { bytea, numericDate, timestamp } from './data-types/index.js';
-
-/** Tag identifier for column type information. */
-export type ColumnTypeTag = 'column';
-
-/** Tag identifier for embedded type configuration. */
-export type EmbeddedConfigTag = 'embedded';
-
-/**
- * Helper type to tag a column type as being a primary key.
- * It wraps the original type `T` and associates Drizzle's `IsPrimaryKey` marker
- * with the underlying Drizzle column builder type stored in the tag metadata.
- * @template T - The original column type (e.g., Uuid, Integer).
- */
-export type IsPrimaryKey<T> =
-  T extends Tagged<unknown, ColumnTypeTag, PgColumnBuilderBase>
-  ? Tagged<UnwrapTagged<T>, ColumnTypeTag, DrizzleIsPrimaryKey<GetTagMetadata<T, ColumnTypeTag>>>
-  : Tagged<T, ColumnTypeTag, DrizzleIsPrimaryKey<ColumnBuilder<T>>>;
-
-/**
- * Helper type to tag a column type as having a default value.
- * It wraps the original type `T` and associates Drizzle's `HasDefault` marker
- * with the underlying Drizzle column builder type stored in the tag metadata.
- * @template T - The original column type (e.g., Uuid, Timestamp).
- */
-export type HasDefault<T> =
-  T extends Tagged<unknown, ColumnTypeTag, PgColumnBuilderBase>
-  ? Tagged<UnwrapTagged<T>, ColumnTypeTag, DrizzleHasDefault<GetTagMetadata<T, ColumnTypeTag>>>
-  : Tagged<T, ColumnTypeTag, DrizzleHasDefault<ColumnBuilder<T>>>;
-
-type EnumColumn<T extends string | number, ColumnName extends string = ''> = PgEnumColumnBuilderInitial<ColumnName, UnionToTuple<`${T}`> extends [string, ...string[]] ? UnionToTuple<`${T}`> : ['NO_VALUES_PROVIDED']>;
-
-type TextTuple<T extends string> = UnionToTuple<`${T}`> extends [string, ...string[]] ? UnionToTuple<`${T}`> : [string];
-
-type HandledColumnName<T extends string = never> = [T] extends [never] ? '' : T;
-
-/**
- * Utility type to infer the Drizzle column builder type based on a TypeScript type `T`.
- * Handles primitive types (string, number, boolean), arrays, enums, Uint8Array,
- * and existing tagged column types.
- * @template T - The TypeScript type to map to a column builder.
- * @template ColumnName - Optional column name for context.
- */
-export type ColumnBuilder<T, ColumnName extends string = never> =
-  HasTag<T> extends true ? T extends Tagged<unknown, ColumnTypeTag, any> ? GetTagMetadata<T, ColumnTypeTag> : never
-  : T extends string ? ReturnType<typeof text<HandledColumnName<ColumnName>, string, TextTuple<T>>>
-  : T extends number ? ReturnType<typeof doublePrecision<HandledColumnName<ColumnName>>>
-  : T extends boolean ? ReturnType<typeof boolean<HandledColumnName<ColumnName>>>
-  : T extends Uint8Array ? ReturnType<typeof bytea<HandledColumnName<ColumnName>>>
-  : T extends EnumerationObject ? EnumColumn<EnumerationValue<T>, HandledColumnName<ColumnName>>
-  : T extends (infer U)[] ? ReturnType<ColumnBuilder<U, HandledColumnName<ColumnName>>['array']>
-  : never;
-
-/**
- * Tagged type representing an embedded class configuration.
- * Stores the embedded type `T` and an optional column name prefix `P`.
- * @template T - The constructor of the class being embedded.
- * @template P - An optional prefix for the column names generated from the embedded class properties.
- */
-export type Embedded<T = AbstractConstructor, P extends string = ''> = Tagged<T, EmbeddedConfigTag, { prefix: P }>;
-
-/**
- * Tagged type representing a PostgreSQL array column.
- * Wraps an existing tagged column type `T` and derives the Drizzle array column builder.
- * @template T - The tagged type of the array elements.
- */
-export type Array<T extends Tagged<ObjectLiteral, ColumnTypeTag, PgColumnBuilder<any>>> = Tagged<UnwrapTagged<T>[], ColumnTypeTag, ReturnType<GetTagMetadata<T, ColumnTypeTag>['array']>>;
-
-/**
- * Tagged type representing a JSONB column.
- * Stores the TypeScript type `T` that the JSONB data represents.
- * @template T - The TypeScript type of the data stored in the JSONB column.
- */
-export type Json<T> = Tagged<T, ColumnTypeTag, $Type<ReturnType<typeof jsonb>, T>>;
-
-/**
- * Tagged type representing a PostgreSQL enum column.
- * Derives the enum values and the Drizzle enum column builder from the provided enum object `T`.
- * @template T - The enumeration object type.
- */
-export type Enum<T extends string | number> = Tagged<T, ColumnTypeTag, EnumColumn<T>>;
-
-export type Text<T extends string = string> = Tagged<string, ColumnTypeTag, ReturnType<typeof text<string, TextTuple<T>>>>;
-
-export type Uuid = Tagged<string, ColumnTypeTag, ReturnType<typeof uuid>>;
-
-export type Integer = Tagged<number, ColumnTypeTag, ReturnType<typeof integer>>;
-
-export type DoublePrecision = Tagged<number, ColumnTypeTag, ReturnType<typeof doublePrecision>>;
-
-export type Boolean = Tagged<number, ColumnTypeTag, ReturnType<typeof boolean>>;
-
-export type Numeric<T extends number | string | bigint = number> = Tagged<T, ColumnTypeTag, ReturnType<typeof numeric<T extends number ? 'number' : T extends string ? 'string' : 'bigint'>>>;
-
-/** Tagged type representing a custom `numericDate` column (stores date as number - days since epoch). */
-export type NumericDate = Tagged<number, ColumnTypeTag, ReturnType<typeof numericDate>>;
-
-/** Tagged type representing a `timestamp` column (stores timestamp as number - milliseconds since epoch). */
-export type Timestamp = Tagged<number, ColumnTypeTag, ReturnType<typeof timestamp>>;
-
-export type Bytea = Tagged<Uint8Array, ColumnTypeTag, ReturnType<typeof bytea>>;
-
-/**
- * Tagged type representing an encrypted column.
- * Stores the original TypeScript type `T`, but the underlying database type is `bytea`.
- * @template T - The original (unencrypted) type of the data.
- */
-export type Encrypted<T> = Tagged<T, ColumnTypeTag, ReturnType<typeof bytea>>;

package/source/orm/utils.ts

@@ -1,25 +0,0 @@
-/**
- * @module
- * Provides utility functions for working with ORM entities.
- */
-import type { Entity, EntityWithoutMetadata } from './entity.js';
-
-/**
- * Converts an array of entities into a Map keyed by entity ID.
- * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
- * @param entities - An array of entities.
- * @returns A Map where keys are entity IDs and values are the corresponding entities.
- */
-export function getEntityMap<T extends Entity | EntityWithoutMetadata>(entities: T[]): Map<string, T> {
-  return new Map(entities.map((entity) => [entity.id, entity]));
-}
-
-/**
- * Extracts the IDs from an array of entities.
- * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
- * @param entities - An array of entities.
- * @returns An array containing the IDs of the entities.
- */
-export function getEntityIds(entities: (Entity | EntityWithoutMetadata)[]): string[] {
-  return entities.map((entity) => entity.id);
-}

package/source/password/README.md

@@ -1,123 +0,0 @@
-# Password Module
-
-A TypeScript module for robust password strength estimation, combining the advanced analysis of `zxcvbn-ts` with checks against the "Have I Been Pwned" database.
-
-## Table of Contents
-
-- [Features](#features)
-- [Core Concepts](#core-concepts)
-- [Usage](#usage)
-  - [Basic Password Check](#basic-password-check)
-  - [Disabling the "Have I Been Pwned" Check](#disabling-the-have-i-been-pwned-check)
-- [API Summary](#api-summary)
-
-## Features
-
-- **Comprehensive Strength Analysis:** Utilizes `zxcvbn-ts` to evaluate passwords against common patterns, dictionary words, keyboard sequences, and more.
-- **Pwned Password Check:** Securely checks if a password has been exposed in a data breach via the "Have I Been Pwned" service.
-- **Simple Scoring:** Provides a clear strength score from 0 (Very Weak) to 4 (Very Strong).
-- **Actionable Feedback:** Returns localized warnings and suggestions to help users choose better passwords.
-- **Secure by Design:** Uses the k-Anonymity model to query the "Have I Been Pwned" API, ensuring the full password hash is never transmitted.
-- **Lightweight:** Dynamically loads `zxcvbn-ts` and its language packs on first use to minimize initial bundle size.
-- **Robust:** Includes a timeout for the "Have I Been Pwned" check to prevent long waits on network issues.
-
-## Core Concepts
-
-This module provides a unified function, `checkPassword`, to assess the security of a password. Its evaluation is based on two primary mechanisms:
-
-### 1. zxcvbn-ts Analysis
-
-The core of the strength estimation comes from the powerful `zxcvbn-ts` library. It analyzes a password by attempting to match it against various patterns, including:
-
-- Dictionary words (from multiple languages)
-- Common names and surnames
-- Well-known keyboard patterns (e.g., `qwerty`, `asdfg`)
-- Repeated characters and sequences (e.g., `aaaa`, `12345`)
-- Dates and common years
-
-Based on this analysis, `zxcvbn-ts` assigns a score from 0 to 4 and provides feedback, which this module translates into localization keys for warnings and suggestions.
-
-### 2. "Have I Been Pwned" (HIBP) Check
-
-To protect against the use of compromised credentials, the module checks the password against the "Have I Been Pwned" Pwned Passwords database. This check is performed securely using a **k-Anonymity** model:
-
-1.  The password is hashed using SHA-1.
-2.  Only the first 5 characters of the hexadecimal hash are sent to the HIBP API.
-3.  The API returns a list of all hash suffixes that share the same 5-character prefix, along with their pwned counts.
-4.  The module searches for the password's hash suffix within the returned list locally.
-
-If a match is found, it means the password has been exposed. In this case, the password strength is automatically considered **Very Weak (score 0)**, regardless of the `zxcvbn-ts` result. This check can be disabled for performance or offline scenarios and will time out gracefully if the API is unresponsive.
-
-## Usage
-
-### Basic Password Check
-
-This example shows how to check a password and use a localization service to display user-friendly feedback. The `warnings` and `suggestions` in the result are localization keys.
-
-```typescript
-import { checkPassword, PasswordStrength, englishPasswordCheckLocalization } from '@tstdl/base/password';
-import { LocalizationService } from '@tstdl/base/text';
-
-// Initialize a localization service with the desired language pack
-const localizationService = new LocalizationService([englishPasswordCheckLocalization]);
-localizationService.setLanguage('en');
-
-async function evaluatePassword(password: string) {
-  try {
-    const result = await checkPassword(password);
-
-    console.log(`Password Strength: ${PasswordStrength[result.strength]} (Score: ${result.strength})`);
-
-    if (result.pwned !== undefined) {
-      if (result.pwned > 0) {
-        console.log(`This password has been pwned ${result.pwned} times!`);
-      } else {
-        console.log('This password was not found in the pwned database.');
-      }
-    }
-
-    if (result.warnings.length > 0) {
-      console.log('Warnings:');
-      // Use the localizationService to display user-friendly messages
-      result.warnings.forEach((warningKey) => console.log(`- ${localizationService.localize(warningKey)}`));
-    }
-
-    if (result.suggestions.length > 0) {
-      console.log('Suggestions:');
-      result.suggestions.forEach((suggestionKey) => console.log(`- ${localizationService.localize(suggestionKey)}`));
-    }
-  } catch (error) {
-    console.error('An error occurred during password check:', error);
-  }
-}
-
-evaluatePassword('password123');
-```
-
-### Disabling the "Have I Been Pwned" Check
-
-For environments without internet access or where maximum performance is critical, you can disable the remote API call.
-
-```typescript
-import { checkPassword } from '@tstdl/base/password';
-
-async function evaluatePasswordOffline(password: string) {
-  const result = await checkPassword(password, { checkForPwned: false });
-
-  // The result.pwned property will be undefined
-  console.log(`Password Strength Score: ${result.strength}`);
-}
-
-evaluatePasswordOffline('a-very-secure-offline-password!');
-```
-
-## API Summary
-
-| Function / Class | Arguments / Properties | Return Type | Description |
-| :--- | :--- | :--- | :--- |
-| `checkPassword` | `password: string`<br>`options?: { checkForPwned?: boolean }` | `Promise<PasswordCheckResult>` | Asynchronously checks password strength using zxcvbn-ts and optionally the HIBP database. |
-| `haveIBeenPwned` | `password: string` | `Promise<number>` | Checks a password against the HIBP database and returns the number of times it has been pwned. |
-| `PasswordCheckResult` | `strength: PasswordStrength`<br>`pwned?: number`<br>`warnings: string[]`<br>`suggestions: string[]` | `class` | The result object returned by `checkPassword`. Warnings and suggestions are localization keys. |
-| `PasswordStrength` | (Enum) | `enum` | An enum representing password strength from `VeryWeak` (0) to `VeryStrong` (4). |
-| `englishPasswordCheckLocalization` | - | `PasswordCheckLocalization` | English localization data for warnings and suggestions. |
-| `germanPasswordCheckLocalization` | - | `PasswordCheckLocalization` | German localization data for warnings and suggestions. |

package/source/password/have-i-been-pwned.ts

@@ -1,29 +0,0 @@
-import { digest } from '#/utils/cryptography.js';
-
-const urlBase = 'https://api.pwnedpasswords.com';
-
-/**
- * Checks password against https://haveibeenpwned.com/passwords
- * @param password password to check
- * @returns how often the password was pwned
- */
-export async function haveIBeenPwned(password: string): Promise<number> {
-  const hash = (await digest('SHA-1', password).toHex()).toUpperCase();
-  const prefix = hash.slice(0, 5);
-  const suffix = hash.slice(5);
-
-  const response = await fetch(`${urlBase}/range/${prefix}`);
-  const result = await response.text();
-
-  const lineStart = result.indexOf(suffix);
-
-  if (lineStart == -1) {
-    return 0;
-  }
-
-  const lineEnd = result.indexOf('\r\n', lineStart);
-  const line = result.slice(lineStart, lineEnd);
-  const pwnedCount = parseInt(line.split(':')[1]!, 10);
-
-  return pwnedCount;
-}