@supatype/cli 0.3.1 → 0.3.3

package/src/type-extractor.ts

@@ -1055,7 +1055,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("file", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,
@@ -1067,7 +1070,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("image", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,
@@ -2898,6 +2904,104 @@ const TIME_UNITS = [
 /** Granularities for `StartOf<>`. */
 const TRUNC_UNITS = ["day", "week", "month", "year"] as const
 
+/**
+ * `After<Base, { days: 30, hours: 9 }>` / `Before<...>`: a point in time plus or minus a
+ * multi-unit duration.
+ *
+ * The interval is re-assembled from parsed integers and matched keywords, exactly as
+ * `parseDurationOperand` does, so no author-supplied text reaches Postgres. A permissive
+ * `"30 days 9 hours"` string would be raw SQL by another name.
+ *
+ * Direction is in the operand name rather than the sign of a component, which is the rule
+ * `Ago`/`FromNow` already follow: a negative amount is refused with a message naming the
+ * opposite operand, because relying on a double negative reads wrongly.
+ */
+function parseOffsetOperand(
+  ref: "After" | "Before",
+  args: readonly ts.TypeNode[],
+  sourceFile: ts.SourceFile,
+): Record<string, unknown> {
+  if (args.length !== 2) {
+    throw new Error(
+      `\`${ref}<>\` takes a base and an interval, as in ` +
+        `\`${ref}<StartOf<"day">, { days: 30, hours: 9 }>\`.`,
+    )
+  }
+
+  const base = parseAccessOperand(args[0]!, sourceFile)
+  const baseKind = typeof base["kind"] === "string" ? base["kind"] : ""
+  if (baseKind !== "now" && baseKind !== "startOf") {
+    throw new Error(
+      `\`${ref}<>\` measures from a point in time, so its base must be \`Now\` or ` +
+        `\`StartOf<unit>\`. A column or a claim depends on the row or the caller and ` +
+        `cannot be offset.`,
+    )
+  }
+
+  const intervalNode = args[1]!
+  if (!ts.isTypeLiteralNode(intervalNode)) {
+    throw new Error(
+      `\`${ref}<>\` takes the interval as an object, as in \`{ days: 30, hours: 9 }\`.`,
+    )
+  }
+
+  const opposite = ref === "After" ? "Before" : "After"
+  const interval: Record<string, number> = {}
+
+  for (const member of intervalNode.members) {
+    if (!ts.isPropertySignature(member) || !member.name || !member.type) {
+      throw new Error(`\`${ref}<>\` interval members must be \`unit: amount\` pairs.`)
+    }
+    const unit = member.name.getText(sourceFile).replace(/["']/g, "")
+    if (!TIME_UNITS.includes(unit as (typeof TIME_UNITS)[number])) {
+      throw new Error(
+        `\`${unit}\` is not a unit of time. Use one of: ${TIME_UNITS.join(", ")} (plural).`,
+      )
+    }
+
+    const amountNode = member.type
+    // A negative literal is a prefix-unary expression, not a numeric literal, so it has
+    // to be recognised separately or it is refused for the wrong reason and the message
+    // misses the real advice.
+    if (
+      ts.isLiteralTypeNode(amountNode) &&
+      ts.isPrefixUnaryExpression(amountNode.literal) &&
+      amountNode.literal.operator === ts.SyntaxKind.MinusToken
+    ) {
+      throw new Error(
+        `\`${ref}<>\` does not take a negative amount. For the other direction use ` +
+          `\`${opposite}<>\`, which reads correctly instead of relying on a double negative.`,
+      )
+    }
+    if (!ts.isLiteralTypeNode(amountNode) || !ts.isNumericLiteral(amountNode.literal)) {
+      throw new Error(`\`${unit}\` needs a number literal amount, as in \`{ ${unit}: 30 }\`.`)
+    }
+    const amount = Number(amountNode.literal.text)
+    if (!Number.isInteger(amount)) {
+      throw new Error(
+        `\`{ ${unit}: ${amount} }\` must be a whole number of units: Postgres intervals ` +
+          `take integers, so a fraction would be silently truncated or rejected.`,
+      )
+    }
+    if (unit in interval) {
+      throw new Error(`\`${ref}<>\` names \`${unit}\` twice; give each unit once.`)
+    }
+    interval[unit] = amount
+  }
+
+  // An all-zero interval means the base unchanged, which is never what an author wrote.
+  // The engine refuses it too, but saying so here names the operand at the point it was
+  // written rather than at push.
+  if (Object.values(interval).every((amount) => amount === 0)) {
+    throw new Error(
+      `\`${ref}<>\` was given an empty interval, which means the base unchanged. ` +
+        `Give at least one non-zero unit, as in \`{ days: 30 }\`.`,
+    )
+  }
+
+  return { kind: ref === "After" ? "after" : "before", base, interval }
+}
+
 /**
  * `Ago<30, "days">` / `FromNow<7, "days">`.
  *
@@ -3056,6 +3160,9 @@ function parseAccessOperand(
       case "Ago":
       case "FromNow":
         return parseDurationOperand(ref, operandArgs, sourceFile)
+      case "After":
+      case "Before":
+        return parseOffsetOperand(ref, operandArgs, sourceFile)
       case "Claim": {
         const pathArg = typeNode.typeArguments?.[0]
         if (!pathArg || !ts.isLiteralTypeNode(pathArg) || !ts.isStringLiteral(pathArg.literal)) {

package/src/type-generation.ts

@@ -13,9 +13,26 @@
  */
 
 import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname, resolve } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 import { generateClientAugmentation } from "./augmentation-generator.js"
 import { ensureEngine, engineRequest } from "./engine-client.js"
+import { generateProjectClient } from "./client-generator.js"
+
+/** The client a project imports, beside the generated types. */
+const PROJECT_CLIENT_FILENAME = "client.ts"
+
+/**
+ * Where generated output goes when a project has not said otherwise.
+ *
+ * Exported because two commands need the same answer: `generate` writes these files and
+ * `seed` reads one of them, and when they disagreed the builder was written to a path the
+ * seed run then reported as missing.
+ */
+export const DEFAULT_TYPES_PATH = "types/database.ts"
+export const DEFAULT_CLIENT_PATH = "supatype/generated/index.d.ts"
+
+/** The seed builder, beside the client, because both are generated from the same schema. */
+const SEED_BUILDER_FILENAME = "seed.ts"
 
 export interface GenerateTypesRequest {
   cwd: string
@@ -26,6 +43,39 @@ export interface GenerateTypesRequest {
   clientPath?: string | undefined
 }
 
+/**
+ * Where the generated seed builder lives for this project.
+ *
+ * One rule, exported, because two things need the answer and a seed run that looked
+ * somewhere else would report a missing builder for a file that had just been written.
+ */
+export function seedBuilderPath(req: {
+  typesPath?: string | undefined
+  clientPath?: string | undefined
+}): string | undefined {
+  const directory = req.clientPath ?? req.typesPath
+  if (directory === undefined || directory === "") return undefined
+  return join(dirname(directory), SEED_BUILDER_FILENAME)
+}
+
+/**
+ * The same answer for a project that has configured nothing.
+ *
+ * `generate` writes with the defaults applied, so a reader must resolve them the same way or
+ * it looks for a file beside a path the project never set.
+ */
+export function seedBuilderPathWithDefaults(output?: {
+  types?: string | undefined
+  client?: string | undefined
+}): string {
+  return (
+    seedBuilderPath({
+      typesPath: output?.types ?? DEFAULT_TYPES_PATH,
+      clientPath: output?.client ?? DEFAULT_CLIENT_PATH,
+    }) ?? join(dirname(DEFAULT_CLIENT_PATH), SEED_BUILDER_FILENAME)
+  )
+}
+
 /** Writes what was asked for and returns one message per file, for the caller to report. */
 export async function writeGeneratedTypes(req: GenerateTypesRequest): Promise<string[]> {
   const written: string[] = []
@@ -48,7 +98,45 @@ export async function writeGeneratedTypes(req: GenerateTypesRequest): Promise<st
     written.push(`Types written to ${req.typesPath}`)
   }
 
-  // Generated locally from the AST, so it needs no engine round trip.
+  const seedPath = seedBuilderPath(req)
+  if (seedPath !== undefined) {
+    await ensureEngine()
+    const result = await engineRequest<{ code?: string; message?: string }>("/generate", {
+      ast: req.ast,
+      lang: "typescript",
+      artifact: "seed",
+    })
+    const code = result.code ?? result.message
+    if (code === undefined) {
+      throw new Error("Engine returned no output for the seed builder.")
+    }
+    const outPath = resolve(req.cwd, seedPath)
+    mkdirSync(dirname(outPath), { recursive: true })
+    writeFileSync(outPath, code, "utf8")
+    written.push(`Seed builder written to ${toPosix(seedPath)}`)
+  }
+
+  written.push(...writeAstDerivedOutputs(req))
+
+  return written
+}
+
+/**
+ * The generated files that come from the AST alone, with no engine round trip.
+ *
+ * Shared because three commands need them and only one was writing them. `push` and `generate`
+ * call {@link writeGeneratedTypes}; `dev` has its own type generation, for good reasons it should
+ * keep, and so never wrote these at all. The result was a project developed entirely through
+ * `supatype dev` that never received `index.d.ts`, so the module augmentation that makes
+ * `createClient` typed without a generic never happened, and never received the generated client,
+ * so every exact-value column fell back to asking the API.
+ *
+ * Kept separate from the types branch above rather than folding `dev` into it: that branch slices
+ * the engine's output from a marker and treats a failure as fatal, and `dev` must do neither.
+ */
+export function writeAstDerivedOutputs(req: GenerateTypesRequest): string[] {
+  const written: string[] = []
+
   if (req.clientPath !== undefined && req.clientPath !== "") {
     const outPath = resolve(req.cwd, req.clientPath)
     mkdirSync(dirname(outPath), { recursive: true })
@@ -56,5 +144,26 @@ export async function writeGeneratedTypes(req: GenerateTypesRequest): Promise<st
     written.push(`Client augmentation written to ${req.clientPath}`)
   }
 
+  // The client the project imports. One file carrying the augmentation, the exact-value columns
+  // and a re-export of `createClient`, so an app writes a single import and tsconfig cannot lose
+  // any of it. See `client-generator.ts` for what each part replaced.
+  // Beside `output.client` when set, otherwise beside `output.types`. A project that configured
+  // only types still gets a usable client: this one file carries the augmentation and the exact
+  // columns as well as `createClient`, so without it the project has types and no way to use them
+  // that knows anything about its schema.
+  const clientDir = req.clientPath ?? req.typesPath
+  if (clientDir !== undefined && clientDir !== "") {
+    const relative = join(dirname(clientDir), PROJECT_CLIENT_FILENAME)
+    const outPath = resolve(req.cwd, relative)
+    mkdirSync(dirname(outPath), { recursive: true })
+    writeFileSync(outPath, generateProjectClient(req.ast), "utf8")
+    written.push(`Client written to ${toPosix(relative)}`)
+  }
+
   return written
 }
+
+/** Reported with forward slashes, so the message reads the same on every platform. */
+function toPosix(path: string): string {
+  return path.split(sep).join("/")
+}

package/tests/access-composition.test.ts

@@ -580,6 +580,129 @@ export type Post = Model<{
     })
   })
 
+
+  // `After` / `Before`: a point in time plus or minus a multi-unit duration. The
+  // composition `Ago` and `FromNow` could not express, because they carry one amount
+  // and one unit.
+  it("extracts a composed offset from a truncation base", () => {
+    const post = extract(
+      `
+import type { Model, UUID, All, Gte, Lte, After, Before, Now, StartOf } from "@supatype/types"
+
+export type Post = Model<{
+  id: UUID
+}, {
+  access: {
+    read: All<[
+      Gte<"starts_at", After<StartOf<"day">, { days: 30, hours: 9 }>>,
+      Lte<"created_at", Before<Now, { weeks: 2 }>>
+    ]>
+  }
+}>
+`,
+      "offsets",
+    )
+
+    expect(access(post)["read"]).toEqual({
+      type: "all",
+      rules: [
+        {
+          type: "compare",
+          op: "gte",
+          left: { kind: "column", name: "starts_at" },
+          right: {
+            kind: "after",
+            base: { kind: "startOf", unit: "day" },
+            interval: { days: 30, hours: 9 },
+          },
+        },
+        {
+          type: "compare",
+          op: "lte",
+          left: { kind: "column", name: "created_at" },
+          right: {
+            kind: "before",
+            base: { kind: "now" },
+            interval: { weeks: 2 },
+          },
+        },
+      ],
+    })
+  })
+
+  // The base is what makes an offset meaningful. A column depends on the row, so it is
+  // not a point in time an offset can be measured from, and the engine refuses one too.
+  it("rejects a base that is not a point in time", () => {
+    expect(() =>
+      extract(
+        `
+import type { Model, UUID, Gte, After, Ago } from "@supatype/types"
+export type Post = Model<{ id: UUID }, {
+  access: { read: Gte<"a", After<Ago<1, "days">, { days: 1 }>> }
+}>
+`,
+        "offset-base",
+      ),
+    ).toThrow(/must be `Now` or `StartOf/)
+  })
+
+  it("rejects an unknown unit inside the interval", () => {
+    expect(() =>
+      extract(
+        `
+import type { Model, UUID, Gte, After, Now } from "@supatype/types"
+export type Post = Model<{ id: UUID }, {
+  access: { read: Gte<"a", After<Now, { dayz: 30 }>> }
+}>
+`,
+        "offset-unit",
+      ),
+    ).toThrow(/is not a unit of time/)
+  })
+
+  // Same rule as Ago/FromNow: direction lives in the operand name, not in a sign, so a
+  // negative amount is refused with the opposite operand named.
+  it("rejects a negative or fractional amount and names the opposite operand", () => {
+    const bad = (n: string) => `
+import type { Model, UUID, Gte, After, Now } from "@supatype/types"
+export type Post = Model<{ id: UUID }, {
+  access: { read: Gte<"a", After<Now, { days: ${n} }>> }
+}>
+`
+    expect(() => extract(bad("-5"), "offset-neg")).toThrow(/does not take a negative amount/)
+    expect(() => extract(bad("-5"), "offset-neg2")).toThrow(/`Before<>`/)
+    expect(() => extract(bad("0.5"), "offset-frac")).toThrow(/whole number/)
+  })
+
+  // An all-zero interval means the base unchanged, which is never what an author wrote.
+  it("rejects an interval that sums to nothing", () => {
+    expect(() =>
+      extract(
+        `
+import type { Model, UUID, Gte, After, Now } from "@supatype/types"
+export type Post = Model<{ id: UUID }, {
+  access: { read: Gte<"a", After<Now, { days: 0 }>> }
+}>
+`,
+        "offset-zero",
+      ),
+    ).toThrow(/empty interval/)
+  })
+
+  it("rejects a unit given twice", () => {
+    expect(() =>
+      extract(
+        `
+import type { Model, UUID, Gte, After, Now } from "@supatype/types"
+export type Post = Model<{ id: UUID }, {
+  access: { read: Gte<"a", After<Now, { days: 1, days: 2 }>> }
+}>
+`,
+        "offset-dup",
+      ),
+    ).toThrow(/twice/)
+  })
+
   // A permissive `"30 days"` string would be raw SQL by another name, so the amount
   // and unit are validated separately and the interval is reassembled from them.
   it("rejects a fractional or negative amount", () => {

package/tests/ast-derived-outputs.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The generated files that need no engine, and which `dev` never wrote.
+ *
+ * `push` and `generate` go through `writeGeneratedTypes`. `dev` has its own type generation, which
+ * it should keep: it slices the engine's output from a marker and treats a failure as a warning
+ * rather than killing the session. What it should not have had is its own idea of which files
+ * exist, and the result was that a project developed entirely through `supatype dev` never
+ * received the module augmentation that types `createClient` without a generic.
+ *
+ * Both files come from the AST alone, so they are shared and all three commands write them.
+ */
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { writeAstDerivedOutputs } from "../src/type-generation.js"
+
+const ast = {
+  models: [
+    {
+      name: "JobPost",
+      annotations: { db: { tableName: "job_post" } },
+      fields: {
+        id: { kind: "uuid", required: true },
+        views: { kind: "bigInt", required: true },
+      },
+    },
+  ],
+}
+
+let cwd: string
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), "supatype-outputs-"))
+})
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+describe("writeAstDerivedOutputs", () => {
+  it("writes the augmentation and the project client together", () => {
+    const written = writeAstDerivedOutputs({
+      cwd,
+      ast,
+      typesPath: "supatype/generated/database.ts",
+      clientPath: "supatype/generated/index.d.ts",
+    })
+
+    expect(existsSync(join(cwd, "supatype/generated/index.d.ts"))).toBe(true)
+    expect(existsSync(join(cwd, "supatype/generated/client.ts"))).toBe(true)
+    expect(written).toHaveLength(2)
+  })
+
+  it("puts the client beside the generated types", () => {
+    // An app imports it by a relative path, so it has to land next to the rest of the generated
+    // output rather than at the project root.
+    writeAstDerivedOutputs({ cwd, ast, clientPath: "supatype/generated/index.d.ts" })
+    const body = readFileSync(join(cwd, "supatype/generated/client.ts"), "utf8")
+
+    expect(body).toContain('export * from "@supatype/client"')
+    expect(body).toContain('declare module "@supatype/client"')
+    expect(body).toContain('"views": "bigint"')
+  })
+
+  it("writes nothing when a project configured no output at all", () => {
+    // `push` must not start creating files in projects that never asked for any.
+    expect(writeAstDerivedOutputs({ cwd, ast })).toEqual([])
+    expect(existsSync(join(cwd, "supatype"))).toBe(false)
+  })
+
+  it("needs no engine, so it can run when type generation could not", () => {
+    // This is why it is separate: in `dev` the engine may be unavailable, and the augmentation and
+    // the client should still reach the project.
+    const written = writeAstDerivedOutputs({ cwd, ast, clientPath: "supatype/generated/index.d.ts" })
+    expect(written.some((line) => line.includes("Client written"))).toBe(true)
+  })
+})
+
+describe("a project that configured only types", () => {
+  it("still gets a client, beside the types", () => {
+    // Otherwise it has generated types and no way to use them that knows its schema: the
+    // augmentation and the exact-value columns both travel in this file.
+    const dir = mkdtempSync(join(tmpdir(), "supatype-types-only-"))
+    try {
+      writeAstDerivedOutputs({ cwd: dir, ast, typesPath: "supatype/generated/database.ts" })
+      expect(existsSync(join(dir, "supatype/generated/client.ts"))).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})