@rebasepro/utils 0.17.3-canary.gdd23447 → 0.18.0

package/src/dates.ts

@@ -1,69 +0,0 @@
-export const defaultDateFormat = "MMMM dd, yyyy, HH:mm:ss";
-
-/** Seven days, the distance past which a relative phrase stops being useful. */
-const DEFAULT_MAX_MS = 7 * 24 * 60 * 60 * 1000;
-
-export type FormatRelativeTimeOptions = {
-    /**
-     * The instant the distance is measured from. Defaults to the current time.
-     * Pass it explicitly to make a caller testable without faking the clock.
-     */
-    now?: Date | number;
-    /**
-     * How far a value may sit from {@link now} and still be described
-     * relatively. Beyond it the function returns `null` and the caller renders
-     * an absolute date instead. Defaults to seven days.
-     */
-    maxMs?: number;
-};
-
-function toTime(value: Date | string | number | null | undefined): number | null {
-    if (value === null || value === undefined || value === "") return null;
-    const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
-    return Number.isNaN(time) ? null : time;
-}
-
-/**
- * Describes an instant relative to another one — "5m ago", "in 3h".
- *
- * The direction is part of the answer. Every hand-rolled version of this in the
- * codebase computed `now - then` and then tested only the positive side, so a
- * timestamp in the future fell through to whichever branch happened to be
- * first: a date scheduled for next month read "Just now", and one a couple of
- * hours out read "-1d ago". Both are dates a CMS holds all the time — a publish
- * date, a due date, an expiry — and neither shape can occur here, because the
- * distance is measured with {@link Math.abs} and the tense is chosen from the
- * sign rather than assumed.
- *
- * Returns `null` when the value is unreadable, or when it is further than
- * {@link FormatRelativeTimeOptions.maxMs} away in either direction. `null` is
- * "say it another way", not an error: the caller owns the absolute format, and
- * the locale and precision that go with it.
- */
-export function formatRelativeTime(
-    value: Date | string | number | null | undefined,
-    options: FormatRelativeTimeOptions = {}
-): string | null {
-    const then = toTime(value);
-    if (then === null) return null;
-
-    const now = options.now instanceof Date ? options.now.getTime() : (options.now ?? Date.now());
-    const maxMs = options.maxMs ?? DEFAULT_MAX_MS;
-
-    // Positive is the past, which is the only case the callers used to handle.
-    const delta = now - then;
-    const distance = Math.abs(delta);
-    if (distance > maxMs) return null;
-
-    const future = delta < 0;
-
-    const minutes = Math.floor(distance / 60_000);
-    if (minutes < 1) return future ? "in a moment" : "just now";
-    if (minutes < 60) return future ? `in ${minutes}m` : `${minutes}m ago`;
-
-    const hours = Math.floor(distance / 3_600_000);
-    if (hours < 24) return future ? `in ${hours}h` : `${hours}h ago`;
-
-    const days = Math.floor(distance / 86_400_000);
-    return future ? `in ${days}d` : `${days}d ago`;
-}

package/src/fields.ts

@@ -1,27 +0,0 @@
-
-
-export function isDefaultFieldConfigId(id: string): boolean {
-    return ["text_field",
-        "multiline",
-        "markdown",
-        "url",
-        "email",
-        "switch",
-        "select",
-        "multi_select",
-        "number_input",
-        "number_select",
-        "multi_number_select",
-        "file_upload",
-        "multi_file_upload",
-        "reference",
-        "multi_references",
-        "relation",
-        "date_time",
-        "group",
-        "key_value",
-        "repeat",
-        "custom_array",
-        "block"
-    ].includes(id);
-}

package/src/flatten_object.ts

@@ -1,49 +0,0 @@
-export function flattenObject(obj: Record<string, unknown>, parentKey = "") {
-    if (!obj) return obj;
-    return Object.keys(obj).reduce((flatObj, key) => {
-        const newKey = parentKey ? `${parentKey}.${key}` : key;
-
-        if (typeof obj[key] === "object" && obj[key] !== null) {
-            if (Array.isArray(obj[key])) {
-                obj[key].forEach((item: unknown, index: number) => {
-                    if (typeof item === "object" && item !== null) {
-                        Object.assign(flatObj, flattenObject(item as Record<string, unknown>, `${newKey}[${index}]`));
-                    } else {
-                        flatObj[`${newKey}[${index}]`] = item;
-                    }
-                });
-            } else {
-                Object.assign(flatObj, flattenObject(obj[key] as Record<string, unknown>, newKey));
-            }
-        } else {
-            flatObj[newKey] = obj[key];
-        }
-
-        return flatObj;
-    }, {} as { [key: string]: unknown });
-}
-
-
-// map from nested property key like "a.b.c" to the maximum array count found in a list of objects for that array
-export type ArrayValuesCount = Record<string, number>;
-
-export function getArrayValuesCount(array: Record<string, unknown>[]): ArrayValuesCount {
-    return array.reduce((acc: ArrayValuesCount, obj: Record<string, unknown>) => {
-        Object.entries(obj).forEach(([key, value]) => {
-            // proceed only if value is an array
-            if (Array.isArray(value)) {
-                acc[key] = Math.max(acc[key] || 0, value.length);
-            }
-
-            // handle nested object
-            if (typeof value === "object" && value !== null) {
-                const nested = getArrayValuesCount([value as Record<string, unknown>]);
-                Object.entries(nested).forEach(([nestedKey, nestedCount]) => {
-                    const compoundKey = `${key}.${nestedKey}`;
-                    acc[compoundKey] = Math.max(acc[compoundKey] || 0, nestedCount);
-                });
-            }
-        });
-        return acc;
-    }, {});
-}

package/src/hash.ts

@@ -1,12 +0,0 @@
-export function hashString(str: string): number {
-    if (!str) return 0;
-    let hash = 0;
-    let i;
-    let chr;
-    for (i = 0; i < str.length; i++) {
-        chr = str.charCodeAt(i);
-        hash = ((hash << 5) - hash) + chr;
-        hash |= 0; // Convert to 32bit integer
-    }
-    return Math.abs(hash);
-}

package/src/index.ts

@@ -1,13 +0,0 @@
-export * from "./strings";
-export * from "./objects";
-export * from "./arrays";
-export * from "./dates";
-export * from "./storage";
-export * from "./hash";
-export * from "./sha1";
-export * from "./policy-names";
-export * from "./regexp";
-export * from "./flatten_object";
-export * from "./plurals";
-export * from "./names";
-export * from "./fields";

package/src/names.ts

@@ -1,186 +0,0 @@
-import { singular } from "./plurals";
-import { toSnakeCase } from "./strings";
-
-/**
- * Generates a foreign key column name from a given string, typically a collection slug or name.
- * It singularizes the name, converts it to snake_case and appends '_id'.
- *
- * Singularization runs *before* snake-casing so that acronyms survive: `toSnakeCase`
- * splits on every capital, which turned "URLs" into "ur_ls" and then "ur_l_id".
- *
- * @param name The base name to convert to a foreign key.
- * @returns A foreign key name in the format 'singular_name_id'.
- *
- * @example
- * // returns "user_id"
- * generateForeignKeyName("users")
- *
- * @example
- * // returns "category_id"
- * generateForeignKeyName("categories")
- *
- * @example
- * // returns "product_id"
- * generateForeignKeyName("Product")
- *
- */
-export function generateForeignKeyName(name: string): string {
-    return `${toSnakeCase(singularizeForKey(name))}_id`;
-}
-
-/**
- * `singular()` handles real English plurals, but its final catch-all rule strips
- * any trailing "s", which mangles words that only look plural. Guard the two
- * cases that produce a column name nobody would recognise:
- *
- * - a double "s" ending is never a plural marker ("address", "class", "process"),
- *   so stripping it yields "addres";
- * - a name that singularizes to nothing (the literal "s") would yield "_id".
- */
-function singularizeForKey(name: string): string {
-    if (/ss$/i.test(name)) return name;
-    const result = singular(name);
-    return result.length > 0 ? result : name;
-}
-
-/**
- * What `generateForeignKeyName` returned before it learned to singularize:
- * snake-case the name, then chop one trailing "s".
- *
- * This is here to be *detected*, never to be generated. A database provisioned
- * under the old rule carries `categorie_id`, `addresse_id`, `children_id` or
- * `ur_l_id` where the current rule expects `category_id`, `address_id`,
- * `child_id` and `url_id` — and the boot-time schema ensure is additive, so it
- * would create the new column empty beside the populated old one and leave the
- * relation reading nothing. No error, no missing table: the failure is silent,
- * which is the only reason this function still exists.
- *
- * `ensureCollectionSchema` calls it to recognise that shape and say so.
- * Returns the same string as `generateForeignKeyName` for every regular plural,
- * so a caller can compare the two and act only when they differ.
- */
-export function legacyForeignKeyName(name: string): string {
-    const snake = toSnakeCase(name);
-    return `${snake.endsWith("s") ? snake.slice(0, -1) : snake}_id`;
-}
-
-/**
- * Truncate an identifier to what Postgres will actually store.
- *
- * Postgres silently truncates identifiers at NAMEDATALEN-1 = 63 **bytes**, so a
- * name generated longer than that is not the name the database ends up holding.
- * Anything that later looks the object up by the name it generated then misses.
- *
- * Byte length, not string length: NAMEDATALEN is a byte bound, and a multi-byte
- * character straddling the boundary would be cut mid-sequence by `slice(0, 63)`.
- *
- * `TextEncoder` rather than `Buffer`, which is not a matter of taste: `Buffer`
- * is a Node global, and this package is imported by browser-facing ones. It
- * typechecked only where `@types/node` happened to be in scope, so
- * `packages/codegen` — whose tsconfig is `lib: ["ESNext", "dom"]` — could not
- * compile the file at all, and both of its suites failed to run. `TextEncoder`
- * and `TextDecoder` are standard in both runtimes and need no ambient types.
- */
-export function toPostgresIdentifier(name: string): string {
-    return truncateToBytes(name, 63);
-}
-
-/**
- * {@link toPostgresIdentifier} with the bound lifted to a parameter.
- *
- * Exists for names that end in something load-bearing. Truncating at 63 keeps
- * the *head* of a name and discards the tail, which is right for a descriptive
- * identifier and wrong for a hashed one: the hash is the part that makes it
- * unique, and it is at the end. A caller that appends a fingerprint truncates
- * the readable head to `63 - <tail>` itself and then appends, so the bound is
- * still 63 and the hash always survives.
- *
- * `contracts/derived-names.txt` records what the alternative costs — a foreign
- * key frozen as `..._corres`, its `_fkey` suffix truncated away, so a second
- * foreign key on that table would derive a byte-identical name.
- *
- * One truncation rule, in one function, so the two cannot drift.
- */
-export function truncateToBytes(name: string, maxBytes: number): string {
-    const bytes = new TextEncoder().encode(name);
-    if (bytes.byteLength <= maxBytes) return name;
-    // Decoding a slice that ends mid-character yields U+FFFD; dropping it lands
-    // on the last whole character that fits, which is what Postgres does.
-    return new TextDecoder("utf-8").decode(bytes.subarray(0, maxBytes)).replace(/�+$/, "");
-}
-
-/**
- * The API name a database column is served under.
- *
- * The wire name of a field is its property key, and Rebase's property keys are
- * camelCase — `displayName`, `createdAt`, `photoURL`. Columns are snake_case,
- * because an unquoted Postgres identifier folds to lower case and a camelCase
- * column is therefore reachable only as `"authorId"` forever: in hand-written
- * SQL, in psql, in an RLS policy body, in a dump, and in every third-party tool
- * that ever touches the database. So the two conventions are both right, and
- * this is the function that crosses between them.
- *
- * It exists because two sources of field names never crossed: a foreign key
- * derived from a relation (`author_id`) and a column read back by introspection
- * (`user_id`) both landed on the wire under their column name, while every
- * hand-authored collection next to them used camelCase. One API, two
- * conventions, and no rule a caller could infer from outside — those names are
- * also the `where` and `orderBy` keys, so it was not a matter of taste.
- *
- * Rules, in the order they matter:
- *
- *  - **A name with no separator is returned unchanged.** `photoURL` stays
- *    `photoURL` and `id` stays `id`. Lower-casing a single token is what makes
- *    a "camelCase" helper destructive — `camelCase("photoURL")` is `photourl` —
- *    and this function is applied to names that are *already* keys.
- *  - **Each following segment keeps its own casing** apart from an upper-cased
- *    first letter, so `photo_URL` → `photoURL` rather than `photoUrl`.
- *  - **The result may still not be a JavaScript identifier.** `2fa_enabled`
- *    becomes `2faEnabled`, which is a perfectly good object key and still needs
- *    quoting where one is written into generated source.
- *
- * Not the inverse of {@link toSnakeCase}: `toSnakeCase` tokenises on case
- * boundaries and would turn `photoURL` into `photo_url`. Round-tripping is not
- * a property either function promises, which is why a column name that a
- * property maps explicitly is always read off `columnName` rather than derived.
- */
-export function toWireKey(columnName: string): string {
-    if (!columnName) return columnName;
-    const segments = columnName.split(/[-_ ]+/).filter(Boolean);
-    if (segments.length <= 1) return columnName;
-    return segments
-        .map((segment, index) =>
-            index === 0
-                ? segment.charAt(0).toLowerCase() + segment.slice(1)
-                : segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join("");
-}
-
-/**
- * The first candidate key not already used, or a numbered fallback.
- *
- * Introspection turns a set of column names into a set of object keys, and the
- * mapping is not injective: `user_id` and `userId` are two columns and one
- * {@link toWireKey}, and two foreign keys can strip to the same relation name.
- * A duplicate key in a generated object literal is a TypeScript error, so the
- * whole collection stops compiling — and a duplicate key in a `Record` built at
- * runtime is worse, because it silently drops a column instead.
- *
- * The numbered tail is what makes this total: a function that returns a key it
- * cannot guarantee is free has only moved the duplicate one line down.
- *
- * Structurally typed on `has` so a `Map` of emitted blocks and a `Set` of taken
- * names both satisfy it. Lives here, in the package both introspection
- * producers and the admin's table import can reach, because they must resolve a
- * collision the same way or one database describes itself three ways.
- */
-export function firstFreeKey(candidates: string[], taken: { has(key: string): boolean }): string {
-    for (const candidate of candidates) {
-        if (!taken.has(candidate)) return candidate;
-    }
-    const base = candidates[candidates.length - 1];
-    for (let suffix = 2; ; suffix++) {
-        const candidate = `${base}_${suffix}`;
-        if (!taken.has(candidate)) return candidate;
-    }
-}