@dogsbay/types 0.2.0-beta.156 → 0.2.0-beta.158

package/dist/index.d.ts

@@ -11,3 +11,5 @@ export { WELL_KNOWN_FIELDS, INERT_FIELDS, AGGREGATOR_OWNED, EMPTY_POLICY, typeOf
 export type { FieldType, FieldSpec, PropSpec, TaxonomySpec, FrontmatterPolicy } from "./frontmatter-schema.js";
 export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-check.js";
 export type { FrontmatterFinding } from "./frontmatter-check.js";
+export type { ImportLimits, LimitName, LimitHost } from "./limits.js";
+export { DEFAULT_LIMITS, LIMIT_DESCRIPTIONS, LIMIT_REACHED, resolveLimits, parseLimit, formatLimit, limitMessage, utf8Bytes } from "./limits.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export { treeToJson, chunkByHeadings, extractText } from "./json.js";
 export { STATUS_VALUES, parseMeta } from "./meta.js";
 export { WELL_KNOWN_FIELDS, INERT_FIELDS, AGGREGATOR_OWNED, EMPTY_POLICY, typeOf, matchesType, nearMisses, isSafeAutoFix, frontmatterKeyLines, globMatches, contentRelativePath, requiredFieldsFor, } from "./frontmatter-schema.js";
 export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-check.js";
+export { DEFAULT_LIMITS, LIMIT_DESCRIPTIONS, LIMIT_REACHED, resolveLimits, parseLimit, formatLimit, limitMessage, utf8Bytes } from "./limits.js";

package/dist/limits.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Import limits: the RESOURCE limits an import puts on someone else's repo, in one place
+ * (plans/import-limits.md). They exist so a hostile repo cannot make an import read gigabytes or
+ * build a table of a million rows; for the operator's own repo they are only a way for content
+ * to turn into a note, so `trusted` sets none.
+ *
+ * Who may set them: the OPERATOR (CLI flags, a host's `migrate()` options), never the repo being
+ * imported. Safety rules (containment, no repo code run, escaping) are NOT limits and are not
+ * here: they hold whether the repo is trusted or not.
+ *
+ * Each default is measured against the largest real value it guards, with the headroom noted.
+ * A limit that trips is REPORTED (`LIMIT_REACHED`), never silent.
+ */
+export interface ImportLimits {
+    /** One file read as data (bytes). */
+    fileBytes: number;
+    /** Files in one data folder. */
+    folderFiles: number;
+    /** All data read in one import (bytes). */
+    importBytes: number;
+    /** Data one catalogue (a table built from data files) may read (bytes). */
+    catalogueBytes: number;
+    /** Rows in one catalogue. */
+    catalogueRows: number;
+    /** Characters of text in one table cell. */
+    cellChars: number;
+}
+export type LimitName = keyof ImportLimits;
+/**
+ * The defaults, for a repo that is not trusted. Measured on cloudflare-docs (6e85ac29,
+ * 2026-11-03), the largest real use of each today:
+ */
+export declare const DEFAULT_LIMITS: Readonly<ImportLimits>;
+/** What each limit guards, for the report. */
+export declare const LIMIT_DESCRIPTIONS: Readonly<Record<LimitName, string>>;
+/** The ledger code a tripped limit is reported under. */
+export declare const LIMIT_REACHED = "limit-reached";
+/**
+ * The limits an import runs with: the defaults, or none when `trusted`, then each given value.
+ * A given value must be a positive number (or Infinity); anything else throws, naming it — a typo
+ * must not run with a limit the operator did not mean.
+ */
+export declare function resolveLimits(given?: Partial<Record<string, unknown>>, opts?: {
+    trusted?: boolean;
+}): ImportLimits;
+/**
+ * One `--limit name=value` flag: `catalogueBytes=500MB`, `catalogueRows=50000`, `cellChars=none`.
+ * Sizes take `KB`/`MB`/`GB` (powers of 1,000) or `KiB`/`MiB`/`GiB`; `none` is no limit.
+ */
+export declare function parseLimit(flag: string): [LimitName, number];
+/** A limit's value as a person reads it: `256 MB`, `20,000`, `none`. */
+export declare function formatLimit(name: LimitName, value: number): string;
+/**
+ * How an operator raises a limit, by where the import runs: the CLI's flags, `site build`'s config,
+ * a host's options (the playground). The report names the one that works where it is read.
+ */
+export type LimitHost = "cli" | "config" | "host";
+/**
+ * The report for a tripped limit: what was not done, the measured value against the limit, and
+ * how to raise it where the import runs.
+ */
+export declare function limitMessage(what: string, name: LimitName, measured: number | undefined, limit: number, host?: LimitHost): string;
+/** UTF-8 bytes of a string, without encoding it: limits on bytes count bytes, not UTF-16 units. */
+export declare function utf8Bytes(s: string): number;

package/dist/limits.js

@@ -0,0 +1,147 @@
+/**
+ * Import limits: the RESOURCE limits an import puts on someone else's repo, in one place
+ * (plans/import-limits.md). They exist so a hostile repo cannot make an import read gigabytes or
+ * build a table of a million rows; for the operator's own repo they are only a way for content
+ * to turn into a note, so `trusted` sets none.
+ *
+ * Who may set them: the OPERATOR (CLI flags, a host's `migrate()` options), never the repo being
+ * imported. Safety rules (containment, no repo code run, escaping) are NOT limits and are not
+ * here: they hold whether the repo is trusted or not.
+ *
+ * Each default is measured against the largest real value it guards, with the headroom noted.
+ * A limit that trips is REPORTED (`LIMIT_REACHED`), never silent.
+ */
+/**
+ * The defaults, for a repo that is not trusted. Measured on cloudflare-docs (6e85ac29,
+ * 2026-11-03), the largest real use of each today:
+ */
+export const DEFAULT_LIMITS = Object.freeze({
+    // largest model JSON 496 KB → 32×
+    fileBytes: 16_000_000,
+    // catalog-models holds 199 files → 100×
+    folderFiles: 20_000,
+    // all the data files in Cloudflare's src/content (JSON/YAML outside the pages): 15.6 MB → 64×;
+    // the whole src/content, pages included, is 54.7 MB
+    importBytes: 1_000_000_000,
+    // the model catalogue reads 14.1 MB of JSON → 18×
+    catalogueBytes: 256_000_000,
+    // 272 models, 193 fields → 70×
+    catalogueRows: 20_000,
+    // longest model description 611 characters → 16×
+    cellChars: 10_000,
+});
+/** What each limit guards, for the report. */
+export const LIMIT_DESCRIPTIONS = Object.freeze({
+    fileBytes: "bytes in one data file",
+    folderFiles: "files in one data folder",
+    importBytes: "data read in one import",
+    catalogueBytes: "data one catalogue reads",
+    catalogueRows: "rows in one catalogue",
+    cellChars: "characters in one table cell",
+});
+/** The ledger code a tripped limit is reported under. */
+export const LIMIT_REACHED = "limit-reached";
+/** Every limit unset: what `trusted` gives. */
+const NONE = Object.freeze({
+    fileBytes: Infinity,
+    folderFiles: Infinity,
+    importBytes: Infinity,
+    catalogueBytes: Infinity,
+    catalogueRows: Infinity,
+    cellChars: Infinity,
+});
+const isLimitName = (k) => Object.hasOwn(DEFAULT_LIMITS, k);
+/**
+ * The limits an import runs with: the defaults, or none when `trusted`, then each given value.
+ * A given value must be a positive number (or Infinity); anything else throws, naming it — a typo
+ * must not run with a limit the operator did not mean.
+ */
+export function resolveLimits(given, opts = {}) {
+    const out = { ...(opts.trusted ? NONE : DEFAULT_LIMITS) };
+    for (const [k, v] of Object.entries(given ?? {})) {
+        if (v === undefined)
+            continue;
+        if (!isLimitName(k))
+            throw new Error(`No such limit: ${k} (there is ${Object.keys(DEFAULT_LIMITS).join(", ")})`);
+        // a whole number ≥ 1, or Infinity (none): `cellChars=0.5` cut a cell to one character and an ellipsis
+        if (typeof v !== "number" || !(v === Infinity || (Number.isInteger(v) && v >= 1)))
+            throw new Error(`Limit ${k} must be a whole number of at least 1 (or none), not ${JSON.stringify(v)}`);
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * One `--limit name=value` flag: `catalogueBytes=500MB`, `catalogueRows=50000`, `cellChars=none`.
+ * Sizes take `KB`/`MB`/`GB` (powers of 1,000) or `KiB`/`MiB`/`GiB`; `none` is no limit.
+ */
+export function parseLimit(flag) {
+    const m = /^([A-Za-z]+)=(.+)$/.exec(flag.trim());
+    if (!m)
+        throw new Error(`--limit takes name=value, not ${JSON.stringify(flag)}`);
+    const [, name, raw] = m;
+    if (!isLimitName(name))
+        throw new Error(`No such limit: ${name} (there is ${Object.keys(DEFAULT_LIMITS).join(", ")})`);
+    if (/^(none|unlimited|infinity)$/i.test(raw))
+        return [name, Infinity];
+    const v = /^(\d+(?:\.\d+)?)\s*([KMG]i?B)?$/i.exec(raw.replace(/_/g, ""));
+    if (!v)
+        throw new Error(`--limit ${name}: ${JSON.stringify(raw)} is not a number (or 500MB, or none)`);
+    const unit = (v[2] ?? "").toUpperCase();
+    if (unit && !name.endsWith("Bytes"))
+        throw new Error(`--limit ${name} is a count, not a size: ${JSON.stringify(raw)}`);
+    const scale = { "": 1, KB: 1e3, MB: 1e6, GB: 1e9, KIB: 1024, MIB: 1024 ** 2, GIB: 1024 ** 3 };
+    // a size rounds to whole bytes; a count must be whole
+    const n = unit ? Math.round(Number(v[1]) * scale[unit]) : Number(v[1]);
+    // only the word `none` means no limit: 400 digits is a typo, not Infinity
+    if (!Number.isFinite(n) || n > Number.MAX_SAFE_INTEGER)
+        throw new Error(`--limit ${name}: ${JSON.stringify(raw)} is too large (use none for no limit)`);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`--limit ${name} must be a whole number of at least 1, not ${JSON.stringify(raw)}`);
+    return [name, n];
+}
+/** A limit's value as a person reads it: `256 MB`, `20,000`, `none`. */
+export function formatLimit(name, value) {
+    if (!Number.isFinite(value))
+        return "none";
+    if (name.endsWith("Bytes")) {
+        if (value >= 1e9)
+            return `${+(value / 1e9).toFixed(1)} GB`;
+        if (value >= 1e6)
+            return `${+(value / 1e6).toFixed(1)} MB`;
+        if (value >= 1e3)
+            return `${+(value / 1e3).toFixed(1)} KB`;
+        return `${value} bytes`;
+    }
+    return value.toLocaleString("en-US");
+}
+const HOW = {
+    cli: (name) => `--limit ${name}=…, or --trusted for a repo you trust`,
+    config: (name) => `\`limits: { ${name}: … }\` in dogsbay.config.yml, or \`limits: { trusted: true }\``,
+    host: (name) => `the import's \`limits.${name}\` option, or \`trusted\` for a repo you trust`,
+};
+/**
+ * The report for a tripped limit: what was not done, the measured value against the limit, and
+ * how to raise it where the import runs.
+ */
+export function limitMessage(what, name, measured, limit, host = "cli") {
+    const over = measured === undefined ? `over the ${formatLimit(name, limit)} limit` : `${formatLimit(name, measured)}, over the ${formatLimit(name, limit)} limit`;
+    return `${what}: ${LIMIT_DESCRIPTIONS[name]} ${over} (${HOW[host](name)})`;
+}
+/** UTF-8 bytes of a string, without encoding it: limits on bytes count bytes, not UTF-16 units. */
+export function utf8Bytes(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00) {
+            n += 4;
+            i++;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/types",
-  "version": "0.2.0-beta.156",
+  "version": "0.2.0-beta.158",
   "description": "Universal document tree model for Dogsbay format loaders and renderers",
   "type": "module",
   "main": "dist/index.js",