@confect/server 9.0.0-next.5 → 9.0.0-next.7

package/CHANGELOG.md

@@ -1,5 +1,168 @@
 # @confect/server
 
+## 9.0.0-next.7
+
+### Patch Changes
+
+- Updated dependencies [5d19484]
+  - @confect/core@9.0.0-next.7
+
+## 9.0.0-next.6
+
+### Major Changes
+
+- 46045a9: Reduce per-function cold-start cost: make `FunctionSpec` schemas lazy and keep each Convex function's bundle scoped to its own group.
+
+  Previously, loading a single Convex function still paid for the whole project — importing the codegen-assembled `_generated/spec.ts` ran `Schema.Struct(...)` / `Schema.Array(...)` for every function at module load, and each per-function bundle transitively imported `_generated/api.ts` → `_generated/spec.ts` (every spec). A function's cold-start cost now scales with its own group rather than the size of the project.
+
+  ### Lazy `FunctionSpec` schemas
+
+  `FunctionSpec.*` (`publicQuery` / `internalQuery` / `publicMutation` / `internalMutation` / `publicAction` / `internalAction` / `publicNodeAction` / `internalNodeAction`) takes `args`, `returns`, and (optional) `error` as `() => Schema` thunks instead of bare schemas. The resulting provenance exposes them as sync lazy memoised getters (the same pattern `Table.make` uses), so importing `_generated/spec.ts` builds no schemas — construction is deferred to the first invocation that compiles validators or runs a codec.
+
+  Migration — wrap each schema in `() =>`:
+
+  ```diff
+    FunctionSpec.publicQuery({
+      name: "list",
+  -   args: Schema.Struct({}),
+  -   returns: Schema.Array(notes.Doc),
+  +   args: () => Schema.Struct({}),
+  +   returns: () => Schema.Array(notes.Doc),
+    })
+  ```
+
+  ### Impls take the `DatabaseSchema`, and group paths resolve impl-side
+
+  `FunctionImpl.make` and `GroupImpl.make` now take the runtime `DatabaseSchema` (the default export of `_generated/schema.ts`) as their first argument instead of the whole `Api`. The handler's ctx-service types only ever depended on the database schema, and switching impls to import `_generated/schema` instead of `_generated/api` removes `_generated/spec.ts` (and the function specs it transitively imports) from every per-function bundle.
+
+  Each function also registers under a flat, single-segment key into a fresh, isolated `Registry` provided per group by `RegisteredFunctions.buildForGroup` (and the CLI's impl validation), so no group-path lookup against `api.spec` is needed. As a result `Spec#addPath`, `Spec#paths`, and `Api.resolveGroupPathUnsafe` are removed; `GroupImpl` / `FunctionImpl` drop their group-path type parameter; and the codegen-emitted `_generated/spec.ts` / `nodeSpec.ts` no longer contain a `.addPath(...)` chain (the `.addAt(...)` / `.addGroupAt(...)` assembly tree that `Refs.make` consumes is unchanged).
+
+  Migration — in each `*.impl.ts`, import the database schema and pass it where you passed `api` / `nodeApi`:
+
+  ```diff
+  - import api from "../_generated/api";        // (or nodeApi from "../_generated/nodeApi")
+  + import databaseSchema from "../_generated/schema";
+
+  - const insert = FunctionImpl.make(api, notes, "insert", handler);
+  + const insert = FunctionImpl.make(databaseSchema, notes, "insert", handler);
+
+  - export default GroupImpl.make(api, notes).pipe(Layer.provide(insert), GroupImpl.finalize);
+  + export default GroupImpl.make(databaseSchema, notes).pipe(Layer.provide(insert), GroupImpl.finalize);
+  ```
+
+  Node impls migrate identically (from `nodeApi` to the same `_generated/schema`); only their specs differ (`GroupSpec.makeNode()`). Hand-rolled tests that built a `Spec` via `.addPath(group, "dot.path")` should drop those calls.
+
+  ### `buildForGroup` and the generated registries
+
+  `RegisteredFunctions.buildForGroup` takes the `DatabaseSchema` value plus the group's own `GroupSpec` as a single type argument (`buildForGroup<typeof groupSpec>(…)`, returning `RegisteredFunctionsForGroupSpec<Group>`); the `api` / `groupPath` parameters and the `ForGroupPath` dot-path navigation are gone. `RegisteredConvexFunction.make` / `RegisteredNodeFunction.make` take the `DatabaseSchema` rather than the `Api`. Each `_generated/registeredFunctions/{path}.ts` imports the runtime schema and references its group's leaf spec **type-only** (`typeof import("…/{group}.spec")["default"]`), so it never imports a spec module at runtime.
+
+  ### `_generated/api.ts` / `nodeApi.ts` are no longer emitted, and `Api` is removed
+
+  Nothing imports them anymore, so `confect codegen` no longer emits `_generated/api.ts` / `_generated/nodeApi.ts` and deletes any copies left over from earlier versions. The `Api` module itself (`@confect/server/Api` — `Api.make`, the `Api` type, `Api.resolveGroupPathUnsafe`, etc.) is **removed entirely**: impls and the generated registries take the `DatabaseSchema` value and the spec directly, so the combined database-schema-plus-spec `Api` is no longer used anywhere.
+
+  ### Net effect
+
+  A function's `convex/{path}.ts` bundle now imports only its own group's registry → its own `.impl` + `_generated/schema` (table schemas, built lazily) + its own group's spec. No `_generated/api.ts`, no project-wide `_generated/spec.ts`, and no sibling-group impls/specs. Re-run `confect codegen` after upgrading.
+
+- 762f7eb: Split the deploy-time Convex schema from the runtime `DatabaseSchema`, make `confect/tables/` the single source of truth — including the table name, which is now derived from the filename — and make per-table schema construction lazy.
+
+  Previously, `confect/schema.ts` was user-authored and `DatabaseSchema` carried a `convexSchemaDefinition` field that was eagerly rebuilt on every `.addTable(...)`. That field was an `O(n²)` allocation for `n` tables, and it forced both the deploy CLI (which only needs `defineSchema(...)`) and the runtime (which only needs the table codec lookup) through the same module — so any runtime function bundle dragged in `convex/server`'s `defineSchema`. Issue 1.
+
+  Codegen now scans `confect/tables/*.ts` (every file must default-export a `Table`) and emits two siblings:
+  - `confect/_generated/schema.ts` — the runtime `DatabaseSchema`, consumed by `_generated/api.ts`. Imports `@confect/server` but never `convex/server`.
+  - `confect/_generated/convexSchema.ts` — the Convex deploy `SchemaDefinition`, re-exported one-line from `convex/schema.ts`. Imports `convex/server` but never `@confect/server`.
+
+  The `convexSchemaDefinition` field is removed from `DatabaseSchema` and `Api`. `TestConfect.layer` now takes the Convex schema definition as a separate argument so it can stay aligned with the deploy artifact without bringing the runtime schema along for the ride.
+
+  ### Filename-derived table names
+
+  The table name is now derived from the file's basename — `confect/tables/notes.ts` defines a table called `notes`. `Table.make` no longer accepts a name argument and returns an _unnamed_ `Table` value; codegen invokes that value with the filename to produce the bound table.
+
+  This eliminates a class of subtle infelicities: the file basename and the table name can never drift out of sync, cross-table `_id` references are type-constrained against the actual set of declared tables (catching typos at compile time), and ESM cycle hazards for mutual cross-table `Id` references are gone because authoring files no longer transitively import each other.
+
+  Codegen now emits two new sets of files alongside `_generated/schema.ts` and `_generated/convexSchema.ts`:
+  - `confect/_generated/id.ts` — a single `Id` constructor whose argument is type-constrained to the union of your table names. Use `Id("notes")` everywhere you previously wrote `GenericId.GenericId("notes")`.
+  - `confect/_generated/tables/<name>.ts` — one thin wrapper per table that binds the unnamed value from `confect/tables/<name>.ts` to its filename. This is what other modules (specs, impls, HTTP handlers) default-import to reach a table's `Doc`, `Fields`, and `tableName`.
+
+  Table filenames must be valid JS identifiers, may not start with `_` (Convex reserves underscore-prefixed names for system tables), and may not collide with reserved JS keywords like `import.ts`. Pick a casing convention you like — Confect's example code uses `snake_case` (`notes.ts`, `user_profiles.ts`).
+
+  The bound `Table`'s `name` property has been renamed to `tableName`. This avoids a silent collision with the built-in `Function.prototype.name` that JavaScript carries on every function value (including the new unnamed-callable `UnnamedTable`).
+
+  ### Lazy per-table schema construction
+
+  `Table.make` takes a `() => Schema.Struct({...})` callback rather than a bare struct, and a bound `Table`'s `Fields`, `Doc`, and `tableDefinition` are lazy memoised getters that only invoke that callback on first access.
+
+  Previously, every `confect/tables/<name>.ts` module ran `Schema.Struct({...})` (and the corresponding `compileTableSchema` / `defineTable` work) at module-load time. Because the codegen-emitted `_generated/schema.ts` is imported transitively from every per-group function bundle, loading any one function eagerly built _every_ table's schema graph — paying a cold-start cost proportional to the whole project, not just the function being invoked.
+
+  The bound `Table` now exposes `Fields` / `Doc` / `tableDefinition` as lazy getters that compute their value on first access, then replace themselves with a plain non-writable data property so second-and-subsequent accesses are observably indistinguishable from a plain property (and skip all function-call overhead). The result: a function bundle only pays the schema-construction cost for tables it actually touches via `db.table(name)` (which reaches `Fields` through `Document.decode`). The `UnnamedTable` callable no longer exposes `Fields` or `tableDefinition` — read these off the bound `Table` (the generated `_generated/tables/<name>.ts` wrapper already binds the name).
+
+  ### Migration
+  1. Delete your `confect/schema.ts`. Codegen will refuse to run while a stray copy is present.
+  2. Rename each `confect/tables/<Name>.ts` to a valid JS identifier in your chosen casing convention (e.g. `confect/tables/notes.ts`). The basename becomes the table name; you no longer pass it as an argument.
+  3. Convert each table file to a **default-export-only** unnamed module: drop the name argument from `Table.make`, wrap the field-schema struct in a `() => ...` callback, and switch any `GenericId.GenericId("users")` references to `Id("users")` imported from `../_generated/id`:
+
+     ```diff
+     - import { GenericId } from "@confect/core";
+       import { Table } from "@confect/server";
+       import { Schema } from "effect";
+     + import { Id } from "../_generated/id";
+
+     - export default Table.make(
+     -   "notes",
+     -   Schema.Struct({
+     -     userId: Schema.optional(GenericId.GenericId("users")),
+     -     text: Schema.String,
+     -   }),
+     - );
+     + export default Table.make(() =>
+     +   Schema.Struct({
+     +     userId: Schema.optional(Id("users")),
+     +     text: Schema.String,
+     +   }),
+     + );
+     ```
+
+  4. Rewire every consumer site (specs, impls, integration tests, HTTP handlers, etc.) to import from the generated wrapper rather than directly from `tables/`. The wrapper is also where you now read `Doc` / `Fields` / `tableDefinition` (the unnamed `Table.make(...)` callable no longer exposes them):
+
+     ```diff
+     - import Notes from "../tables/Notes";
+     + import notes from "../_generated/tables/notes";
+
+     - returns: Schema.Array(Notes.Doc),
+     + returns: Schema.Array(notes.Doc),
+     ```
+
+  5. Replace every remaining `GenericId.GenericId("x")` call site with `Id("x")` from `_generated/id` (in spec `args`/`returns`, in `TaggedError` schemas, in `TestConfect.run`, etc.).
+  6. If you read `table.name` anywhere off a bound `Table`, rename it to `table.tableName`.
+  7. Re-run `confect codegen`. It will create `confect/_generated/schema.ts`, `confect/_generated/convexSchema.ts`, `confect/_generated/id.ts`, and one `confect/_generated/tables/<name>.ts` wrapper per table; and it will rewrite `convex/schema.ts` to a one-line re-export.
+  8. If you use `@confect/test`, pass the generated Convex schema definition to `TestConfect.layer`:
+
+     ```diff
+     - import confectSchema from "./confect/schema";
+     + import confectSchema from "./confect/_generated/schema";
+     + import convexSchema from "./confect/_generated/convexSchema";
+
+       export const layer = TestConfect_.layer(
+         confectSchema,
+     +   convexSchema,
+         import.meta.glob("./convex/**/!(*.*.*)*.*s"),
+       );
+     ```
+
+  ### New warning: no tables discovered
+
+  If a Confect project has no tables — either `confect/tables/` is missing entirely or it exists but contains no `.ts` files — codegen now emits a yellow `⚠` warning and continues, producing an empty `DatabaseSchema.make()` / `defineSchema({})`. Table-free backends (e.g. action-only proxies, webhook bridges) are still legal; the warning just catches the much more common case of a typoed directory name or files placed at the wrong path. To silence it, add at least one `Table.make(...)` module under `confect/tables/`.
+
+  ### New error: invalid table filename
+
+  Codegen now rejects table files whose basename is not a valid JS identifier (e.g. `user-profiles.ts`), starts with `_` (reserved for Convex system tables), or shadows a reserved JS keyword (e.g. `import.ts`). Rename the offending file to fix it — for example, `user-profiles.ts` → `user_profiles.ts` or `userProfiles.ts`.
+
+### Patch Changes
+
+- Updated dependencies [46045a9]
+- Updated dependencies [762f7eb]
+  - @confect/core@9.0.0-next.6
+
 ## 9.0.0-next.5
 
 ### Patch Changes

package/dist/Auth.d.ts

@@ -15,7 +15,7 @@ declare const Auth_base: effect_Context0.TagClass<Auth, "@confect/server/Auth",
 }> & {
   use: <X>(body: (_: {
     getUserIdentity: Effect.Effect<convex_server0.UserIdentity, NoUserIdentityFoundError, never>;
-  }) => X) => [X] extends [Effect.Effect<infer A, infer E, infer R>] ? Effect.Effect<A, E, R | Auth> : [X] extends [PromiseLike<infer A_1>] ? Effect.Effect<A_1, effect_Cause0.UnknownException, Auth> : Effect.Effect<X, never, Auth>;
+  }) => X) => [X] extends [Effect.Effect<infer A, infer E, infer R>] ? Effect.Effect<A, E, Auth | R> : [X] extends [PromiseLike<infer A_1>] ? Effect.Effect<A_1, effect_Cause0.UnknownException, Auth> : Effect.Effect<X, never, Auth>;
 };
 declare class Auth extends Auth_base {}
 declare const layer: (auth: Auth$1) => Layer.Layer<Auth, never, never>;