@db3.ai/pure

mkdir -p examples
cp -R node_modules/@db3.ai/pure/examples/. examples/

npx tsx examples/runNoteTags.ts

import { selectedStrings, uniqueNormalizedStrings } from '@db3.ai/pure/collections';

/**
 * Validates tag selection against application-owned options before accepting it.
 *
 * selectedStrings() reports unknown values but retains them in its values array.
 * The application must reject invalid entries before persisting the selection.
 * @param selected - Raw string options already type-checked at the request boundary.
 * @returns Normalized, allowed tags with stable first-occurrence ordering.
 */
export function selectNoteTags(selected: readonly string[]): string[] {
	const options = uniqueNormalizedStrings([' Client ', 'Internal', 'client']);
	const result = selectedStrings(selected, options);
	if (result.invalid.length > 0) throw new Error('Choose a supported note tag.');
	return result.values;
}

import { expect, it } from 'vitest';
import { selectNoteTags } from '../examples/selectNoteTags';

it('normalizes allowed tags but rejects unknown selections before recovery', () => {
	expect(selectNoteTags([' client ', 'CLIENT', ' internal '])).toEqual(['Client', 'Internal']);
	expect(() => selectNoteTags(['Administrator'])).toThrow('supported note tag');
	expect(selectNoteTags(['Internal'])).toEqual(['Internal']);
	expect(selectNoteTags([])).toEqual([]);
});

npx vitest run tests/noteTags.test.ts
npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts

export * from '@db3.ai/pure/ai';
export * from '@db3.ai/pure/auth';
export * from '@db3.ai/pure/collections';
export * from '@db3.ai/pure/dates';
export * from '@db3.ai/pure/errors';
export * from '@db3.ai/pure/http';
export * from '@db3.ai/pure/records';
export * from '@db3.ai/pure/strings';
export * from '@db3.ai/pure/ulid';
export * from '@db3.ai/pure/urls';

import { truncateText } from '@db3.ai/pure/strings';
export interface TextResponsePayload {
    output_text?: unknown;
    output?: unknown;
    error?: {
        message?: unknown;
    };
}
/**
 * Formats unique strings as a Markdown unordered-list block for prompt input.
 *
 * @example
 * ```ts
 * stringListPromptBlock('Audiences', ['Founders', 'Founders']);
 * // 'Audiences:\\n- Founders'
 * ```
 */
export declare function stringListPromptBlock(title: string, values: readonly string[] | null | undefined): string;
/**
 * Reads a text error message from a response-like payload.
 *
 * @example
 * ```ts
 * responseErrorMessage({ error: { message: 'Rate limited' } });
 * // 'Rate limited'
 * ```
 */
export declare function responseErrorMessage(payload: TextResponsePayload | null): string | null;
/**
 * Reads direct or nested output text from a response-like payload.
 *
 * @example
 * ```ts
 * responseOutputText({ output_text: ' Done ' });
 * // 'Done'
 * ```
 */
export declare function responseOutputText(payload: TextResponsePayload | null): string | null;
/**
 * Parses a JSON array of strings or a line/comma-separated list into strings.
 *
 * @example
 * ```ts
 * parseStringList('["seo", "content"]');
 * // ['seo', 'content']
 * ```
 */
export declare function parseStringList(text: string): string[];
/**
 * Parses JSON text after removing an optional Markdown JSON code fence.
 *
 * @example
 * ```ts
 * parseJsonObjectText('```json\\n{"ok":true}\\n```');
 * // { ok: true }
 * ```
 */
export declare function parseJsonObjectText(text: string): unknown;
/**
 * Extracts nested `output_text` content items from an array response shape.
 *
 * @example
 * ```ts
 * outputItemsText([{ content: [{ type: 'output_text', text: 'Hello' }] }]);
 * // 'Hello'
 * ```
 */
export declare function outputItemsText(output: unknown): string;
export { truncateText };

export { bearerToken } from '@db3.ai/pure/http';

/**
 * Removes exact duplicate strings while keeping the first occurrence order.
 *
 * @example
 * ```ts
 * uniqueStrings(['alpha', 'beta', 'alpha']);
 * // ['alpha', 'beta']
 * ```
 */
export declare function uniqueStrings(values: readonly string[]): string[];
/**
 * Normalizes whitespace and removes case-insensitive duplicate strings.
 *
 * @example
 * ```ts
 * uniqueNormalizedStrings([' SEO  Agency ', 'seo agency', 'AI']);
 * // ['SEO Agency', 'AI']
 * ```
 */
export declare function uniqueNormalizedStrings(values: readonly string[]): string[];
export interface SelectedStringsResult {
    values: string[];
    invalid: string[];
}
export type SelectedOrAllStringsResult = SelectedStringsResult;
/**
 * Selects requested values from a saved option list and reports unknown values.
 *
 * @example
 * ```ts
 * selectedStrings([' seo agency '], ['SEO Agency', 'Developers']);
 * // { values: ['SEO Agency'], invalid: [] }
 * ```
 */
export declare function selectedStrings(selected: readonly string[], available: readonly string[] | null | undefined): SelectedStringsResult;
/**
 * Selects requested values from a saved option list, or returns all saved options when no selection is supplied.
 *
 * @example
 * ```ts
 * selectedOrAllStrings([' seo agency '], ['SEO Agency', 'Developers']);
 * // { values: ['SEO Agency'], invalid: [] }
 * ```
 */
export declare function selectedOrAllStrings(selected: readonly string[] | undefined, available: readonly string[] | null | undefined): SelectedStringsResult;

/**
 * Converts a Date or parseable date string to an ISO timestamp.
 *
 * @example
 * ```ts
 * isoDate('2026-01-01T00:00:00Z');
 * // '2026-01-01T00:00:00.000Z'
 * ```
 */
export declare function isoDate(value: Date | string | null | undefined): string | null;
/**
 * Adds whole calendar days to a date.
 *
 * @example
 * ```ts
 * addDays(new Date('2026-01-01T12:00:00Z'), 1).getDate();
 * // 2
 * ```
 */
export declare function addDays(date: Date, days: number): Date;
/**
 * Formats a Date as YYYY-MM-DD in local calendar time.
 *
 * @example
 * ```ts
 * formatDate(new Date(2026, 0, 5));
 * // '2026-01-05'
 * ```
 */
export declare function formatDate(date: Date): string;
/**
 * Converts a numeric or numeric-string id to a finite number.
 *
 * @example
 * ```ts
 * numericId('42');
 * // 42
 * ```
 */
export declare function numericId(value: number | string | null | undefined): number | null;

/**
 * Reads a public API error message from an unknown response body.
 *
 * @example
 * ```ts
 * apiErrorMessage({ message: 'Try again' }, 'Request failed');
 * // 'Try again'
 * ```
 */
export declare function apiErrorMessage(result: unknown, fallback: string): string;
/**
 * Converts an unknown thrown value into a displayable message.
 *
 * @example
 * ```ts
 * unknownErrorMessage(new Error('Nope'));
 * // 'Nope'
 * ```
 */
export declare function unknownErrorMessage(error: unknown): string;
/**
 * Returns true for database-driver errors that may expose SQL internals.
 *
 * @example
 * ```ts
 * isSqlError({ code: 'ER_DUP_ENTRY' });
 * // true
 * ```
 */
export declare function isSqlError(error: unknown): boolean;
/**
 * Decides whether exact SQL error details can be shown for an environment name.
 *
 * @example
 * ```ts
 * shouldExposeSqlErrorDetails('production');
 * // false
 * ```
 */
export declare function shouldExposeSqlErrorDetails(environment?: string): boolean;
/**
 * Returns true only when the runtime has explicitly opted into development behavior.
 *
 * @example
 * ```ts
 * isDevelopmentEnvironment(undefined);
 * // false
 * ```
 */
export declare function isDevelopmentEnvironment(environment?: string): boolean;
/**
 * Converts a SQL driver error into a public message, hiding details in production.
 *
 * @example
 * ```ts
 * publicSqlErrorMessage({ code: 'ER_DUP_ENTRY' }, { environment: 'production' });
 * // 'A database error occurred.'
 * ```
 */
export declare function publicSqlErrorMessage(error: unknown, options?: {
    environment?: string;
    productionMessage?: string;
}): string | null;

/**
 * Extracts a bearer token from an Authorization header value.
 *
 * @example
 * ```ts
 * bearerToken('Bearer sk_test_123');
 * // 'sk_test_123'
 * ```
 */
export declare function bearerToken(header: string | readonly string[] | undefined): string | null;
/**
 * Returns the standard application error code for an HTTP status.
 *
 * @example
 * ```ts
 * errorCodeForStatus(404);
 * // 'not_found'
 * ```
 */
export declare function errorCodeForStatus(statusCode: number): string;
/**
 * Allows only same-site redirect paths and blocks selected prefixes.
 *
 * @example
 * ```ts
 * safeRedirectPath('/app/dashboard', ['/auth/']);
 * // '/app/dashboard'
 * ```
 */
export declare function safeRedirectPath(path: unknown, blockedPrefixes?: readonly string[]): string | null;

/**
 * Checks whether a value is a plain object-like record, excluding arrays and null.
 *
 * @example
 * ```ts
 * isRecord({ message: 'Saved' });
 * // true
 * ```
 */
export declare function isRecord(value: unknown): value is Record<string, unknown>;
/**
 * Returns the input as a record, or an empty record when it is not object-like.
 *
 * @example
 * ```ts
 * recordFromUnknown(null);
 * // {}
 * ```
 */
export declare function recordFromUnknown(value: unknown): Record<string, unknown>;
/**
 * Reads and trims a string field from a record, falling back when it is missing or blank.
 *
 * @example
 * ```ts
 * stringField({ email: ' [email protected] ' }, 'email');
 * // '[email protected]'
 * ```
 */
export declare function stringField(body: Record<string, unknown>, field: string, fallback?: string): string;
/**
 * Reads a boolean field from a record, falling back when the value is not boolean.
 *
 * @example
 * ```ts
 * booleanField({ includeSubdomains: true }, 'includeSubdomains', false);
 * // true
 * ```
 */
export declare function booleanField(body: Record<string, unknown>, field: string, fallback: boolean): boolean;
/**
 * Reads a finite number field from a record, falling back when it is missing or invalid.
 *
 * @example
 * ```ts
 * numberField({ limit: 25 }, 'limit', 10);
 * // 25
 * ```
 */
export declare function numberField(body: Record<string, unknown>, field: string, fallback: number): number;
/**
 * Returns a non-empty string value, or null for anything else.
 *
 * @example
 * ```ts
 * stringValue('headline');
 * // 'headline'
 * ```
 */
export declare function stringValue(value: unknown): string | null;
/**
 * Trims a string-like value, returning the fallback for non-strings.
 *
 * @example
 * ```ts
 * trimmedStringValue('  launch plan  ');
 * // 'launch plan'
 * ```
 */
export declare function trimmedStringValue(value: unknown, fallback?: string): string;
/**
 * Converts finite numbers or numeric strings into a number, otherwise null.
 *
 * @example
 * ```ts
 * numberValue('42');
 * // 42
 * ```
 */
export declare function numberValue(value: unknown): number | null;
/**
 * Returns an ISO string for Date inputs or a non-empty string as supplied.
 *
 * @example
 * ```ts
 * dateTimeStringValue(new Date('2026-01-01T00:00:00.000Z'));
 * // '2026-01-01T00:00:00.000Z'
 * ```
 */
export declare function dateTimeStringValue(value: unknown): string | null;
/**
 * Reads a nested record field, falling back to an empty record.
 *
 * @example
 * ```ts
 * nestedRecord({ keyword_data: { keyword: 'seo' } }, 'keyword_data');
 * // { keyword: 'seo' }
 * ```
 */
export declare function nestedRecord(value: Record<string, unknown>, field: string): Record<string, unknown>;
/**
 * Parses JSON text and requires the result to be an object record.
 *
 * @example
 * ```ts
 * parseJsonRecord('{"job":"crawl"}');
 * // { job: 'crawl' }
 * ```
 */
export declare function parseJsonRecord(input: string, message?: string): Record<string, unknown>;
/**
 * Returns a finite number, or null for missing and non-number values.
 *
 * @example
 * ```ts
 * optionalNumber(12.5);
 * // 12.5
 * ```
 */
export declare function optionalNumber(value: unknown): number | null;
/**
 * Returns a string that contains non-whitespace characters, preserving the original value.
 *
 * @example
 * ```ts
 * optionalString(' keyword ');
 * // ' keyword '
 * ```
 */
export declare function optionalString(value: unknown): string | null;
/**
 * Checks for a promise-like value with a callable `then` method.
 *
 * @example
 * ```ts
 * isPromiseLike(Promise.resolve('done'));
 * // true
 * ```
 */
export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
/**
 * Checks for a promise value with a callable `finally` method.
 *
 * @example
 * ```ts
 * isFinallyPromise(Promise.resolve('done'));
 * // true
 * ```
 */
export declare function isFinallyPromise(value: unknown): value is Promise<unknown>;

/**
 * Collapses runs of whitespace into a single space and trims the result.
 *
 * @example
 * ```ts
 * normalizeWhitespace('  SEO\\n  content   plan  ');
 * // 'SEO content plan'
 * ```
 */
export declare function normalizeWhitespace(input: string): string;
/**
 * Builds a case-insensitive comparison key for human-entered strings.
 *
 * @example
 * ```ts
 * normalizedKey('  Flex   AI  ');
 * // 'flex ai'
 * ```
 */
export declare function normalizedKey(input: string): string;
/**
 * Converts an identifier or slug into display-friendly title text.
 *
 * @example
 * ```ts
 * startCase('targetAudiencePhrases');
 * // 'Target Audience Phrases'
 * ```
 */
export declare function startCase(input: string): string;
/**
 * Converts a display string or identifier into snake_case.
 *
 * @example
 * ```ts
 * snakeCase('Target Audience Phrases');
 * // 'target_audience_phrases'
 * ```
 */
export declare function snakeCase(input: string): string;
/**
 * Converts a model or class name into lower-case prose for messages.
 *
 * @example
 * ```ts
 * displayNameFromIdentifier('PasswordResetToken');
 * // 'password reset token'
 * ```
 */
export declare function displayNameFromIdentifier(input: string): string;
/**
 * Removes blank edge lines and trims each line of a multi-line comment.
 *
 * @example
 * ```ts
 * normalizeDatabaseComment('  First line\\r\\n  Second line  ');
 * // 'First line\\nSecond line'
 * ```
 */
export declare function normalizeDatabaseComment(input: unknown): string | null;
/**
 * Returns a string capped at the requested length, trimming trailing whitespace.
 *
 * @example
 * ```ts
 * truncateText('organic growth workflow', 14);
 * // 'organic growth'
 * ```
 */
export declare function truncateText(value: string, maxLength: number): string;
/**
 * Returns a string capped at the requested length, appending an ellipsis when truncated.
 *
 * @example
 * ```ts
 * truncateWithEllipsis('organic growth workflow', 14);
 * // 'organic growth...'
 * ```
 */
export declare function truncateWithEllipsis(value: string, maxLength: number): string;
/**
 * Escapes text for safe placement inside HTML text or attribute values.
 *
 * @example
 * ```ts
 * escapeHtml('Reset "A&B" <now>');
 * // 'Reset &quot;A&amp;B&quot; &lt;now&gt;'
 * ```
 */
export declare function escapeHtml(input: string): string;
/**
 * Trims strings, removes empty entries, and caps the list length.
 *
 * @example
 * ```ts
 * limitedStrings([' SEO ', '', 'AI'], 1);
 * // ['SEO']
 * ```
 */
export declare function limitedStrings(values: readonly string[], limit?: number): string[];
/**
 * Counts whitespace-separated words in a string, returning zero for nullish text.
 *
 * @example
 * ```ts
 * wordCount('organic growth workflow');
 * // 3
 * ```
 */
export declare function wordCount(value: string | null | undefined): number;
/**
 * Removes a surrounding Markdown JSON code fence from a string.
 *
 * @example
 * ```ts
 * stripJsonCodeFence('```json\\n{"ok":true}\\n```');
 * // '{"ok":true}'
 * ```
 */
export declare function stripJsonCodeFence(input: string): string;

/**
 * Creates a canonical, crypto-random ULID string.
 *
 * The timestamp portion is encoded from the provided date or timestamp, and the
 * random portion is filled with `crypto.getRandomValues()`.
 *
 * @example
 * ```ts
 * const id = ulid();
 * ```
 */
export declare function ulid(date?: Date | number): string;
/**
 * Returns true when a value is a valid ULID-shaped string.
 *
 * ULIDs use Crockford Base32 and exclude I, L, O, and U.
 */
export declare function isUlid(value: unknown): value is string;
/**
 * Extracts the timestamp from a ULID as a `Date`.
 *
 * Accepts lowercase input, since `isUlid` does.
 *
 * @example
 * ```ts
 * const createdAt = ulidTime('01J9XQ3Z5H8B2M4N6P7Q9R0S1T');
 * ```
 */
export declare function ulidTime(value: string): Date;

/**
 * Parses an optional valid port from a string.
 *
 * @example
 * ```ts
 * optionalPort('5174');
 * // 5174
 * ```
 */
export declare function optionalPort(input: string | undefined): number | undefined;
/**
 * Normalizes a website URL or domain to a bare hostname without a leading `www.`.
 *
 * @example
 * ```ts
 * normalizeDomainTarget('https://www.example.com/path');
 * // 'example.com'
 * ```
 */
export declare function normalizeDomainTarget(value: string): string | null;
/**
 * Normalizes an absolute URL or bare domain, removing hashes and repeated path
 * slashes.
 *
 * @example
 * ```ts
 * normalizeUrl('example.com//page#section');
 * // 'https://example.com/page'
 * ```
 */
export declare function normalizeUrl(value: string): string;
/**
 * Safely normalizes a URL, resolving relative paths and collapsing repeated
 * path slashes.
 *
 * @example
 * ```ts
 * tryNormalizeUrl('/pricing//plans#top', 'https://example.com');
 * // 'https://example.com/pricing/plans'
 * ```
 */
export declare function tryNormalizeUrl(value: string, baseUrl?: string): string | null;