primitive-admin 1.0.55 → 1.0.56

package/dist/src/lib/codegen-shared/prettierStable.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Prettier-default-stable emission helpers for the codegen emitters (#1565).
+ *
+ * ─────────────────────────── FORMATTING CONTRACT ───────────────────────────
+ * Generated `*.generated.ts` output MUST be a fixed point of Prettier's DEFAULT
+ * config (printWidth 80, 2-space indent, `trailingComma: "all"`): running
+ * `prettier --write` over a freshly generated file must leave it byte-for-byte
+ * unchanged.
+ *
+ * Why it matters: `databases codegen --check` / `workflows codegen --check`
+ * compare the emission to what is on disk BYTE-FOR-BYTE
+ * (`codegen-shared/generatedFiles.ts`). A consumer whose pipeline runs codegen,
+ * then `prettier --write`, then `--check` in CI (the common shape) fails the
+ * check the moment the emission is not already prettier-formatted, even though
+ * nothing is semantically stale. That is the bug this module fixes.
+ *
+ * By maintainer decision (#1565) there is NO Prettier dependency anywhere — not
+ * at runtime, not as a devDependency, and there is no automated round-trip
+ * test. The contract is upheld by this module plus the exact-output unit tests
+ * in `cli/tests/unit/codegen-prettier-stable.test.ts`.
+ *
+ * **If you change an emitter or this module, verify the contract by hand before
+ * landing:** regenerate a representative output (a database type with long op
+ * names and a projection; a workflow with a long key and a `oneOf` output),
+ * run Prettier's default config over the files, and confirm they are unchanged
+ * and `--check` still passes.
+ *
+ * Note "always emit the multi-line shape" is NOT sufficient on its own:
+ * Prettier COLLAPSES a broken call/parameter/type-argument list that would fit
+ * within 80 columns, so an over-broken construct is just as unstable as an
+ * over-long one. It only preserves an author's line break inside an object
+ * literal / object type. So the helpers below reproduce Prettier's width
+ * decision for the handful of shapes these generators emit, and the emitters
+ * always break the object literals (where the break IS preserved).
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+/** Prettier's default `printWidth`. */
+export declare const PRINT_WIDTH = 80;
+/** `level` indentation levels of 2 spaces (Prettier's default `tabWidth`). */
+export declare function indent(level: number): string;
+/**
+ * A TS string literal for `value`, quoted the way Prettier's DEFAULT config
+ * would (`singleQuote: false`).
+ *
+ * `JSON.stringify` is NOT a fixed point: it always double-quotes and escapes
+ * every embedded `"`, but Prettier picks the quote that needs FEWER escapes
+ * (tie → double), so `JSON.stringify("say \"hi\"")` → `"say \"hi\""` while
+ * Prettier emits `'say "hi"'`, and `codegen --check` then fails on a
+ * semantically identical file (#1565). This reproduces Prettier's `printString`
+ * exactly: start from the canonical `JSON.stringify` escaping (correct for all
+ * control characters), count the quotes to choose the enclosing quote, then
+ * re-escape for that quote.
+ */
+export declare function tsStringLiteral(value: string): string;
+/**
+ * A small model of the TypeScript type expressions the emitters produce. The
+ * emitters build these instead of hand-joining strings so `printType` can make
+ * the same width decision Prettier would at every nesting level.
+ *
+ *   - `atom`         — an identifier, string literal, or any short expression
+ *                      that is emitted verbatim and never wrapped.
+ *   - `block`        — a type that is ALWAYS multi-line (an object type). It
+ *                      renders itself at a given indentation level; Prettier
+ *                      preserves the break, so it never collapses.
+ *   - `union`        — `A | B`, wrapping to Prettier's leading-pipe form.
+ *   - `intersection` — `A & B`.
+ *   - `generic`      — `Name<A, B>`, wrapping to one type argument per line.
+ *   - `array`        — `T[]`, parenthesized when the element needs it.
+ *   - `objectType`   — `{ a: A; b: B }`, breaking one member per line when the
+ *                      inline form does not fit.
+ */
+export type TypeNode = {
+    kind: "atom";
+    text: string;
+} | {
+    kind: "block";
+    render: (level: number) => string;
+} | {
+    kind: "union";
+    members: TypeNode[];
+} | {
+    kind: "intersection";
+    members: TypeNode[];
+} | {
+    kind: "generic";
+    name: string;
+    args: TypeNode[];
+} | {
+    kind: "array";
+    element: TypeNode;
+} | {
+    kind: "objectType";
+    members: string[];
+};
+export declare const atom: (text: string) => TypeNode;
+export declare const block: (render: (level: number) => string) => TypeNode;
+export declare const union: (members: TypeNode[]) => TypeNode;
+export declare const intersection: (members: TypeNode[]) => TypeNode;
+export declare const generic: (name: string, args: TypeNode[]) => TypeNode;
+export declare const arrayOf: (element: TypeNode) => TypeNode;
+/**
+ * An inline-first object type (`{ input: X }`). Unlike `block`, it starts
+ * inline and only breaks when it does not fit — which is exactly what Prettier
+ * does with an object type the emitter writes on one line.
+ */
+export declare const objectType: (members: string[]) => TypeNode;
+/**
+ * `Record<string, T>` — a two-argument generic, so Prettier breaks it open when
+ * a long alias name pushes it past the print width. Never emit it as a plain
+ * atom.
+ */
+export declare const recordOf: (value: string) => TypeNode;
+/**
+ * The node's single-line form, or null when it contains a `block` (which is
+ * always multi-line and can therefore never render inline).
+ */
+export declare function inlineType(node: TypeNode): string | null;
+/**
+ * Render a type expression the way Prettier's default config would.
+ *
+ * The returned string's FIRST line carries NO leading indentation — the caller
+ * has already positioned the cursor at `col`. Continuation lines are indented
+ * relative to `level`.
+ *
+ * @param node    the type expression.
+ * @param col     0-based column where the node's first character sits.
+ * @param level   indentation level for the node's continuation lines.
+ * @param reserve characters that follow the node on its closing line (a
+ *                trailing `;` or `,`), counted in the fit decision so the wrap
+ *                boundary matches Prettier's exactly.
+ */
+export declare function printType(node: TypeNode, col: number, level: number, reserve?: number): string;
+/**
+ * Render `export type <name> = <expr>;` as Prettier would.
+ *
+ * A union moves below the `=` in leading-pipe form (its own rule). Otherwise
+ * the RHS stays on the `=` line if it can REACH ITS FIRST BREAK there — so
+ * `= Record<` / `= QueryResult<` stays and breaks its argument list — and
+ * moves below the `=` whole when it cannot (`=\n  MutationResult;`,
+ * `=\n  QueryResult<Pick<M, "a">>;`). That is Prettier's "fluid" assignment
+ * layout: it fit-tests only up to the right-hand side's first break point, not
+ * its whole width.
+ */
+export declare function renderTypeAlias(name: string, node: TypeNode): string;
+/**
+ * Render an object-type member line (`  name?: T;`) at `level` as Prettier
+ * would. A union that has to break moves below the `name:`; anything else
+ * breaks in place.
+ */
+export declare function renderMember(level: number, name: string, optional: boolean, node: TypeNode): string;
+/**
+ * A parameter (or argument) entry in a parenthesized list. A plain string is
+ * emitted verbatim and can only break BETWEEN entries. A `{ name, type }` entry
+ * carries a structured type so the printer can also break INSIDE it — e.g. a
+ * two-argument `Omit<CreateCronTriggerParams<...>, "workflowKey">` whose type-
+ * argument list Prettier opens up when it overflows. A pre-rendered string
+ * cannot express that break; a `TypeNode` can.
+ */
+export type ParamEntry = string | {
+    name: string;
+    type: TypeNode;
+};
+/**
+ * Render a parenthesized value/parameter list, wrapping to one entry per line
+ * (WITH a trailing comma — Prettier's default is `trailingComma: "all"`) when
+ * the single-line form would not fit. A `{ name, type }` entry whose type is too
+ * wide for its own line breaks INSIDE itself the way Prettier would.
+ *
+ * `prefix` must include its own leading indentation; `level` is the
+ * indentation level of the line `prefix` sits on.
+ */
+export declare function renderParenList(prefix: string, entries: ParamEntry[], tail: string, level: number): string;
+/**
+ * Render a call whose LAST argument is an object literal, the way Prettier's
+ * default config would. Prettier tries three shapes in order and takes the
+ * first that fits, so this does too:
+ *
+ *   1. everything on one line;
+ *   2. "last argument expansion" — hug the object literal, keeping the earlier
+ *      arguments on the call's line and breaking the object's members;
+ *   3. one argument per line (with a trailing comma), the object inline.
+ *
+ * `prefix` (callee + any type arguments) must include its own leading
+ * indentation; `level` is the indentation level of the line it sits on. `tail`
+ * is whatever follows the closing paren (e.g. `","`) and is counted in every
+ * fit decision.
+ *
+ * `objectMembers` is optional: a call with NO trailing object-literal argument
+ * (`define<O>(key, options)`, `subscribe<T>(dbId, key, options)`) passes
+ * `undefined`, and then only two shapes apply — everything on one line, or one
+ * argument per line — since there is no last-argument object to hug.
+ */
+export declare function renderCall(prefix: string, leadingArgs: string[], objectMembers: ObjectMember[] | undefined, level: number, tail?: string): string;
+/**
+ * A member of an emitted object literal: either a bare entry (`...opts`) or a
+ * `key: value` pair, which Prettier may break after the colon when the value is
+ * a long string literal.
+ */
+export type ObjectMember = string | {
+    key: string;
+    value: string;
+};
+/**
+ * Render an arrow function whose body is a single call ending in an object
+ * literal — the shape both codegen factories emit.
+ *
+ * Prettier keeps the body on the `=>` line only when the WHOLE call fits there
+ * on one line; a call that has to break at all moves to its own indented line
+ * (it never hugs the object up onto the `=>` line). `head` is the arrow's
+ * signature through `=>` (it may itself be multi-line if the parameter list
+ * broke); `level` is the indentation level of the body line.
+ */
+export declare function renderArrowCall(opts: {
+    head: string;
+    callee: TypeNode;
+    leadingArgs: string[];
+    objectMembers?: ObjectMember[];
+    level: number;
+    tail?: string;
+}): string;
+/**
+ * Render an object-literal property whose value is an arrow function returning a
+ * single call — the shape the database ops factory emits (`  <op>: (params, …)
+ * => client.databases.executeOperation(…)`).
+ *
+ * Prettier applies its assignment layout to the `key: value` pair: the arrow
+ * stays on the key's line only when it can REACH ITS FIRST BREAK there — the
+ * `(` opening its parameter list. When even that `(` does not fit (a property
+ * key long enough that `<indent><key>: (` passes the print width), Prettier
+ * breaks after the colon and renders the WHOLE arrow — parameter list, return
+ * type, and body — one level deeper:
+ *
+ *     aVeryLongOpName:
+ *       (
+ *         params: P,
+ *         options?: OpsCallOptions,
+ *       ): Promise<R> =>
+ *         client.databases.executeOperation<R>(
+ *           databaseId,
+ *           "aVeryLongOpName",
+ *           { params, ...options },
+ *         ),
+ *
+ * Reproducing that break is what keeps a long-but-legal op name (>= 74
+ * characters, with this file's 4-space property indent) prettier-stable.
+ *
+ * @param level         indentation level of the property line.
+ * @param key           the property key, already quoted if it needs to be.
+ * @param params        the arrow's parameter list entries.
+ * @param signatureTail what follows the parameter list's `)` — e.g.
+ *                      `": Promise<R> =>"`.
+ */
+export declare function renderArrowProperty(opts: {
+    level: number;
+    key: string;
+    params: ParamEntry[];
+    signatureTail: string;
+    callee: TypeNode;
+    leadingArgs: string[];
+    objectMembers?: ObjectMember[];
+    tail?: string;
+}): string;