@confect/server 9.0.1 → 9.1.0

package/CHANGELOG.md

@@ -1,11 +1,36 @@
 # @confect/server
 
+## 9.1.0
+
+### Minor Changes
+
+- 8bbde87: Make Confect's public types declaration-emittable, fixing `TS7056` under `tsc --build` with `composite`/`declaration` (e.g. consuming a Confect backend as a referenced TypeScript project).
+
+  The schema-generic service tags (`DatabaseReader`, `DatabaseWriter`, `VectorSearch`, `QueryCtx`/`MutationCtx`/`ActionCtx`) now back their `Context.GenericTag` with named generic interfaces, and codegen annotates the `_generated/services.ts` exports with the corresponding tag aliases — so declaration emit prints the names by reference instead of re-expanding the whole data model (the example backend's `services.d.ts` drops from ~307 KB to ~5.6 KB).
+
+  Codegen also emits `_generated/docs.ts` — a nominal `interface` per table plus a `Docs` registry — threaded into the reader/writer tags via the `Document.Document<Schema, Table>` helper, so query/mutation helpers print named document types (e.g. `NotesDoc`) with no added annotations. Runtime behaviour is unchanged.
+
+### Patch Changes
+
+- Updated dependencies [4d8a568]
+  - @confect/core@9.1.0
+
+## 9.0.2
+
+### Patch Changes
+
+- dd33006: Fix a crash when `get` by index missed on an index over non-string fields.
+
+  `GetByIndexFailure` declared its `indexFieldValues` as `Schema.Array(Schema.String)` while the actual values can be any Convex value (numbers, bigints, booleans, ids, etc.). Because `Schema.TaggedError` constructors validate at runtime, a `get` by such an index would die with a `ParseError` defect whenever the lookup found no document — instead of failing with the catchable `GetByIndexFailure`. Lookups that found a document were unaffected, so the crash only surfaced on a miss.
+
+  `indexFieldValues` is now typed as an array of unknown values and carries the actual values used in the failed lookup. The error `message` renders them as JSON, handling every Convex value type including `bigint` values from `int64` index fields.
+  - @confect/core@9.0.2
+
 ## 9.0.1
 
 ### Patch Changes
 
 - 445ea9b: Loosen and align dependency ranges across all packages:
-
   - The `convex` peer dependency is now `^1.32.0` in every package (previously pinned exactly to `1.39.1`, or `^1.30.0` in `@confect/react`). The range is validated against convex 1.32.0 through 1.40.0.
   - `@confect/server`'s `@effect/platform-node` peer dependency is now optional — it is only needed when using the `@confect/server/node` entrypoint.
   - `@confect/cli` now uses caret ranges for its `@effect/platform` and `@effect/platform-node` dependencies so they can deduplicate with the versions resolved for `@confect/server`, and no longer declares an unused direct dependency on `@effect/platform-node-shared`.
@@ -25,7 +50,6 @@
   ### Filesystem-driven groups
 
   Your API is now authored as colocated `*.spec.ts`/`*.impl.ts` pairs, one pair per group, and **the file's path within `confect/` is the group's name** (its stem for top-level groups, the dot-joined directory path for nested groups). `GroupSpec.make()` and `GroupSpec.makeNode()` no longer take a name argument.
-
   - Each `*.spec.ts` `export default`s its `GroupSpec` (named co-exports like error classes are still allowed).
   - Each `*.impl.ts` default-imports its sibling spec, passes it to `FunctionImpl.make` / `GroupImpl.make`, and ends the layer pipeline with `GroupImpl.finalize`—a compile-time completeness check that only typechecks once every function the spec declares has a `FunctionImpl` provided.
   - The root `confect/spec.ts`, `confect/impl.ts`, `confect/nodeSpec.ts`, and `confect/nodeImpl.ts` files are gone, along with `Impl.make` and `Impl.finalize`. `confect codegen` deletes any of these (and the stale aggregate `_generated/registeredFunctions.ts` / `_generated/nodeRegisteredFunctions.ts`) on upgrade.
@@ -45,12 +69,11 @@
     Schema.Struct({
       userId: Schema.optional(Id("users")),
       text: Schema.String,
-    })
+    }),
   );
   ```
 
   Codegen emits, alongside it:
-
   - `_generated/schema.ts`—the runtime `DatabaseSchema`. Never imports `convex/server`, so a runtime cold start no longer evaluates `defineSchema(...)`.
   - `_generated/convexSchema.ts`—the Convex deploy `SchemaDefinition`, re-exported from `convex/schema.ts`.
   - `_generated/id.ts`—a type-safe `Id` constructor whose argument is constrained to your table names. Use `Id("notes")` everywhere you previously wrote `GenericId.GenericId("notes")`; cross-table `_id` typos are now caught at compile time.
@@ -70,7 +93,7 @@
       name: "list",
       args: Schema.Struct({}),
       returns: Schema.Array(Notes.Doc),
-    })
+    }),
   );
   ```
 
@@ -89,7 +112,7 @@
       name: "list",
       args: () => Schema.Struct({}),
       returns: () => Schema.Array(notes.Doc),
-    })
+    }),
   );
   ```
 
@@ -100,14 +123,13 @@
   const list = FunctionImpl.make(databaseSchema, notes, "list", handler);
   export default GroupImpl.make(databaseSchema, notes).pipe(
     Layer.provide(list),
-    GroupImpl.finalize
+    GroupImpl.finalize,
   );
   ```
 
   ### Node functions are first-class
 
   A group's runtime is now declared solely by its spec—`GroupSpec.makeNode()` for a Node action group, `GroupSpec.make()` otherwise—mirroring vanilla Convex's per-file `"use node"` directive. The separate `node` namespace is gone: Node specs/impls are ordinary colocated pairs that can live anywhere in `confect/`, and codegen emits the `"use node"` directive based on the spec.
-
   - A Node group at `confect/email.spec.ts` is now reached at `refs.public.email.send` instead of `refs.public.node.email.send`.
   - `@confect/core` removes `Spec.makeNode`, `Spec.merge`, and `Spec.isConvexSpec` / `Spec.isNodeSpec`; `Spec.make()` is a single mixed-runtime container and `Refs.make(spec)` takes one argument. `GroupSpec.makeNode()`, `FunctionSpec.publicNodeAction()` / `internalNodeAction()` are unchanged.
 
@@ -124,7 +146,6 @@
   The codegen bundler now uses [`bundle-require`](https://github.com/egoist/bundle-require), so impls may import third-party packages and use `tsconfig.json` `paths` aliases (`~/*`, `@/*`, …) for their own source. A parent `confect/{path}.spec.ts` may now declare functions alongside a sibling `confect/{path}/` subdirectory of further specs, and codegen reports a clear error on a name collision between the two.
 
   ### Migration
-
   1. **Tables.** Delete `confect/schema.ts`. Rename each table file to a valid JS identifier (e.g. `confect/tables/notes.ts`); the basename becomes the table name. Drop the name argument from `Table.make`, wrap the field struct in `() =>`, and replace `GenericId.GenericId("x")` with `Id("x")` from `_generated/id`. If you read `table.name` off a bound table, rename it to `table.tableName`.
   2. **Specs.** Split each group into a colocated `*.spec.ts` that `export default`s `GroupSpec.make()` (no name). Wrap every `args`/`returns`/`error` in `() =>`. Import a table's `Doc`/`Fields` from its wrapper, `import notes from "./_generated/tables/notes"`.
   3. **Impls.** In each `*.impl.ts`, default-import the sibling spec, import `databaseSchema` from `_generated/schema`, pass it to `FunctionImpl.make` / `GroupImpl.make` in place of `api`, end the pipeline with `GroupImpl.finalize`, and `export default` it. Delete the root `confect/spec.ts`, `impl.ts`, `nodeSpec.ts`, and `nodeImpl.ts` (codegen will also remove them).
@@ -167,13 +188,11 @@
   The `node` namespace existed only because the pre-v9 architecture aggregated every function's impl into one module that all generated `convex/` modules imported; Node functions had to be quarantined into a separate spec/impl/registry tree so Convex-runtime functions wouldn't transitively import Node-only code. v9's per-group isolation removed that constraint, so the namespace was no longer load-bearing — only ergonomic overhead that diverged from vanilla Convex (which identifies Node modules per-file, with no directory requirement).
 
   ### Breaking changes
-
   - **API namespace removed.** A Node group at `confect/email.spec.ts` is now referenced as `refs.public.email.send` instead of `refs.public.node.email.send`. Node groups are ordinary groups in the refs tree, nesting preserved like any other group.
   - **Generated layout changed.** Node modules are emitted at `convex/<path>.ts` (carrying `"use node"`) instead of `convex/node/<path>.ts`, and their registries at `confect/_generated/registeredFunctions/<path>.ts`. The single assembled `confect/_generated/spec.ts` now contains every group regardless of runtime; `confect/_generated/nodeSpec.ts` is no longer generated (codegen deletes any stale copy on upgrade).
   - **`@confect/core` API.** Removed `Spec.makeNode`, `Spec.merge`, and `Spec.isConvexSpec`/`Spec.isNodeSpec`. `Spec` is now a single mixed-runtime container (`Spec.make()` accepts groups of any runtime). `Refs.make(spec)` takes a single argument (the unified spec) instead of `(convexSpec, nodeSpec)`. `GroupSpec.makeNode()`/`makeNodeAt()` and `FunctionSpec.publicNodeAction()`/`internalNodeAction()` are unchanged; `GroupSpec` subgroups may now be of any runtime (a group is just a namespace for its children).
 
   ### Migration
-
   1. Move any `confect/node/<path>.spec.ts`/`.impl.ts` files to wherever you want them under `confect/` (e.g. `confect/<path>.spec.ts`); the `node/` directory has no special meaning anymore. Their specs already use `GroupSpec.makeNode()`, so no spec-body change is needed — only fix the impl's relative import of `_generated/schema` if its depth changed.
   2. Update call sites to drop the `node` segment: `refs.public.node.<group>.<fn>` → `refs.public.<group>.<fn>`.
   3. Replace `Refs.make(spec, nodeSpec)` with `Refs.make(spec)` (codegen does this for `_generated/refs.ts` automatically).
@@ -283,7 +302,6 @@
   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`.
 
@@ -296,7 +314,6 @@
   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`.
 
@@ -313,7 +330,6 @@
   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`:
@@ -403,7 +419,6 @@
   Since `9.0.0-next.1`, codegen has wrapped every parent leaf that has sibling subdirectory specs in `<parent>.addGroupAt("child", <child>)`. Because `GroupSpec.addGroupAt` is immutable, that produced a fresh object in the assembled tree, while the parent's `*.impl.ts` continued to hold a reference to the original imported leaf. The runtime resolver compared by `===`, so every such impl failed `validateImpl` with "Could not resolve group path for the provided GroupSpec." Child impls happened to work only because `GroupSpec.withName` was secretly mutating its argument in place to keep the child's identity stable — an asymmetry that was load-bearing for one half of the API and broken for the other.
 
   ### What changed
-
   - `@confect/core/Spec` carries a new `readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>` field and exposes a chainable `Spec#addPath(group, path)` builder. `add` / `addAt` / `merge` propagate `paths` unchanged; `merge` re-prefixes a node spec's entries with `"node."` to match the merged tree.
   - `@confect/core/GroupSpec.withName` is now pure: it returns a fresh copy when the name differs and no longer rewrites the input in place. No new identity-tracking machinery is introduced.
   - `@confect/server/FunctionImpl.make` and `GroupImpl.make` resolve their group path via `api.spec.paths.get(group)` — an O(1) map lookup instead of a tree walk — and throw a clearer error pointing at `Spec.addPath` when the spec hasn't been registered.
@@ -411,7 +426,6 @@
   - `@confect/cli` codegen emits one `.addPath(<binding>, "<dot.path>")` call per leaf in `_generated/spec.ts` (and `_generated/nodeSpec.ts`) so the imported leaves carry their full paths into the assembled spec value.
 
   ### User-facing impact
-
   - Spec authoring (`*.spec.ts`) and impl authoring (`*.impl.ts`) APIs are unchanged. `FunctionImpl.make(api, spec, name, handler)` and `GroupImpl.make(api, spec)` keep their exact signatures.
   - Generated `_generated/spec.ts` (and `_generated/nodeSpec.ts`) pick up one `.addPath(...)` chain entry per leaf on the next `confect codegen` run. The shape is fully immutable — no module-load mutation, no hidden side effects.
   - Hand-rolled tests that construct a `Spec` and pass it to `Api.make` must now also call `.addPath(spec, "dot.path")` for any group they intend to look up.
@@ -450,7 +464,6 @@
   Splitting impl across colocated `*.impl.ts` files is the vehicle for fixing that. With this change, `confect codegen` emits one `_generated/registeredFunctions/{path}.ts` per group, and each generated `convex/` module imports only its own group's per-group registry — which in turn imports only its own sibling `.impl.ts`. A Convex function's cold-start bundle now scales with its own group's impl rather than with the size of the whole project.
 
   ### Breaking changes
-
   - `GroupSpec.make()` and `GroupSpec.makeNode()` no longer take a name argument; the group name is derived from the spec file's path within `confect/`.
   - `FunctionImpl.make(api, groupSpec, fn, handler)` and `GroupImpl.make(api, groupSpec)` now take the imported sibling spec object as their second argument instead of a dot-path string.
   - Every `GroupImpl` pipeline must end with `GroupImpl.finalize`, which only typechecks once every function declared by the spec has a corresponding `FunctionImpl` provided to the group layer. `GroupImpl.finalize` snapshots the names of every registered function onto the produced `Finalized` `GroupImpl` service value, and `confect codegen` reads those names to verify per-function coverage against the spec at runtime.
@@ -459,7 +472,6 @@
   - Every module under `convex/` is re-emitted to import from `_generated/registeredFunctions/{path}` instead of the previous aggregate file. Users who commit `convex/` to source control should expect a full rewrite of that directory on first codegen.
 
   ### Migration
-
   1. For each existing group, create a colocated `confect/{path}.spec.ts` and `confect/{path}.impl.ts` pair (under a subdirectory for nested groups).
      - In each spec, call `GroupSpec.make()` (or `GroupSpec.makeNode()`) without a name and `export default` the result.
      - In each impl, default-import the sibling spec (e.g. `import notes from "./notes.spec"`), pass it to `FunctionImpl.make`/`GroupImpl.make` in place of the previous dot-path string, append `GroupImpl.finalize` to the pipeline, and `export default` the resulting `GroupImpl` layer:
@@ -467,7 +479,7 @@
        export default GroupImpl.make(api, notes).pipe(
          Layer.provide(list),
          Layer.provide(insert),
-         GroupImpl.finalize
+         GroupImpl.finalize,
        );
        ```
   2. Delete root `confect/spec.ts`, `confect/impl.ts`, `confect/nodeSpec.ts`, `confect/nodeImpl.ts`, and any parent aggregator spec/impl files. (`confect codegen` will also delete any of these it finds, plus the stale `_generated/registeredFunctions.ts` and `_generated/nodeRegisteredFunctions.ts`, so this step can be skipped.)
@@ -525,7 +537,7 @@
 
   export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
     "NoteNotFound",
-    { noteId: GenericId.GenericId("notes") }
+    { noteId: GenericId.GenericId("notes") },
   ) {}
 
   export const notes = GroupSpec.make("notes").addFunction(
@@ -534,7 +546,7 @@
       args: Schema.Struct({ noteId: GenericId.GenericId("notes") }),
       returns: Notes.Doc,
       error: NoteNotFound,
-    })
+    }),
   );
   ```
 
@@ -554,7 +566,7 @@
         .table("notes")
         .get(noteId)
         .pipe(Effect.mapError(() => new NoteNotFound({ noteId })));
-    })
+    }),
   );
   ```
 
@@ -626,7 +638,6 @@
   Unspecified failures continue to reject the promise.
 
   ### Migration
-
   - For each `useQuery` call site, replace `result === undefined` checks and direct property access with `QueryResult.match` (or the lower-level `QueryResult.isLoading`/`isSuccess`/`isFailure` predicates).
   - For each `useMutation`/`useAction` call site whose ref now declares an `error` schema, unwrap the resolved `Either` (e.g. with `Either.match`); call sites against refs without an `error` schema need no change.
 

package/dist/ActionCtx.d.ts

@@ -1,5 +1,6 @@
 import type { GenericActionCtx, GenericDataModel } from "convex/server";
 import * as Context from "effect/Context";
-export declare const ActionCtx: <DataModel extends GenericDataModel>() => Context.Tag<GenericActionCtx<DataModel>, GenericActionCtx<DataModel>>;
-export type ActionCtx<DataModel extends GenericDataModel> = ReturnType<typeof ActionCtx<DataModel>>["Identifier"];
+export type ActionCtxTag<DataModel extends GenericDataModel> = Context.Tag<GenericActionCtx<DataModel>, GenericActionCtx<DataModel>>;
+export declare const ActionCtx: <DataModel extends GenericDataModel>() => ActionCtxTag<DataModel>;
+export type ActionCtx<DataModel extends GenericDataModel> = GenericActionCtx<DataModel>;
 //# sourceMappingURL=ActionCtx.d.ts.map

package/dist/ActionCtx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionCtx.d.ts","sourceRoot":"","sources":["../src/ActionCtx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,eAAO,MAAM,SAAS,GAAI,SAAS,SAAS,gBAAgB,4EACkB,CAAC;AAE/E,MAAM,MAAM,SAAS,CAAC,SAAS,SAAS,gBAAgB,IAAI,UAAU,CACpE,OAAO,SAAS,CAAC,SAAS,CAAC,CAC5B,CAAC,YAAY,CAAC,CAAC"}
+{"version":3,"file":"ActionCtx.d.ts","sourceRoot":"","sources":["../src/ActionCtx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,gBAAgB,IAAI,OAAO,CAAC,GAAG,CACxE,gBAAgB,CAAC,SAAS,CAAC,EAC3B,gBAAgB,CAAC,SAAS,CAAC,CAC5B,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,SAAS,SAAS,gBAAgB,OAC/B,YAAY,CAAC,SAAS,CACmD,CAAC;AAE/E,MAAM,MAAM,SAAS,CAAC,SAAS,SAAS,gBAAgB,IACtD,gBAAgB,CAAC,SAAS,CAAC,CAAC"}

package/dist/ActionCtx.js.map

@@ -1 +1 @@
-{"version":3,"file":"ActionCtx.js","names":[],"sources":["../src/ActionCtx.ts"],"sourcesContent":["import type { GenericActionCtx, GenericDataModel } from \"convex/server\";\nimport * as Context from \"effect/Context\";\n\nexport const ActionCtx = <DataModel extends GenericDataModel>() =>\n  Context.GenericTag<GenericActionCtx<DataModel>>(\"@confect/server/ActionCtx\");\n\nexport type ActionCtx<DataModel extends GenericDataModel> = ReturnType<\n  typeof ActionCtx<DataModel>\n>[\"Identifier\"];\n"],"mappings":";;;;;AAGA,MAAa,kBACX,QAAQ,WAAwC,4BAA4B"}
+{"version":3,"file":"ActionCtx.js","names":[],"sources":["../src/ActionCtx.ts"],"sourcesContent":["import type { GenericActionCtx, GenericDataModel } from \"convex/server\";\nimport * as Context from \"effect/Context\";\n\nexport type ActionCtxTag<DataModel extends GenericDataModel> = Context.Tag<\n  GenericActionCtx<DataModel>,\n  GenericActionCtx<DataModel>\n>;\n\nexport const ActionCtx = <\n  DataModel extends GenericDataModel,\n>(): ActionCtxTag<DataModel> =>\n  Context.GenericTag<GenericActionCtx<DataModel>>(\"@confect/server/ActionCtx\");\n\nexport type ActionCtx<DataModel extends GenericDataModel> =\n  GenericActionCtx<DataModel>;\n"],"mappings":";;;;;AAQA,MAAa,kBAGX,QAAQ,WAAwC,4BAA4B"}