@confect/core 10.0.0-next.22 → 10.0.0-next.24

package/src/MiddlewareSpec.ts

@@ -38,9 +38,8 @@ export interface SuccessValue {
 
 /**
  * The wrap-style middleware implementation shape: receives the downstream
- * effect (the remaining middleware plus the function handler) and the
- * covered invocation's metadata, and returns the effect that runs in its
- * place.
+ * effect (the remaining middleware plus the function handler) and the covered
+ * invocation's metadata, and returns the effect that runs in its place.
  *
  * Mirrors `RpcMiddleware.RpcMiddleware` in Effect.
  */
@@ -68,8 +67,8 @@ export interface AnyMiddlewareImpl {
 }
 
 /**
- * The class shape produced by {@link MiddlewareSpec}. Only the static side is ever
- * used—the class is a value-level carrier for the middleware's key, its
+ * The class shape produced by {@link MiddlewareSpec}. Only the static side is
+ * ever used—the class is a value-level carrier for the middleware's key, its
  * declared functionTypes, and its (lazily-evaluated) error schema, plus the
  * type-level `Provides`/`Error` metadata. It is deliberately not a
  * `Context.Tag`: implementations are registered through the group `Registry`
@@ -133,8 +132,8 @@ export type Provides<MiddlewareSpec_ extends AnyMiddlewareSpec> =
     : never;
 
 /**
- * The services a middleware's implementation may consume from middleware
- * that runs earlier in the same chain (type-level only, like `provides`).
+ * The services a middleware's implementation may consume from middleware that
+ * runs earlier in the same chain (type-level only, like `provides`).
  */
 export type Requires<MiddlewareSpec_ extends AnyMiddlewareSpec> =
   MiddlewareSpec_ extends AnyMiddlewareSpec
@@ -165,16 +164,20 @@ export type FunctionTypes<MiddlewareSpec_ extends AnyMiddlewareSpec> =
  * encode through, and the function types it may attach to.
  *
  * ```ts
- * class RequireUser extends MiddlewareSpec.MiddlewareSpec<RequireUser, {
- *   provides: CurrentUser
- * }>()("RequireUser", {
+ * class RequireUser extends MiddlewareSpec.MiddlewareSpec<
+ *   RequireUser,
+ *   {
+ *     provides: CurrentUser;
+ *   }
+ * >()("RequireUser", {
  *   error: () => NotSignedIn,
  *   functionTypes: { query: true, mutation: true, action: false },
  * }) {}
  * ```
  *
  * The implementation is server-only and supplied separately via
- * `MiddlewareImpl.make` (or `makeByFunctionType`/`provides`) in `@confect/server`.
+ * `MiddlewareImpl.make` (or `makeByFunctionType`/`provides`) in
+ * `@confect/server`.
  */
 export const MiddlewareSpec =
   <Self, Config extends { provides?: any; requires?: any } = {}>() =>
@@ -265,10 +268,9 @@ type FunctionTypeOf<FunctionSpec_ extends FunctionSpec.AnyWithProps> =
 type ValidationResult<Errors> = [Errors] extends [never] ? unknown : Errors;
 
 /**
- * A matching-type Convex-provenance function is rejected rather than
- * silently skipped: its raw handler passes through Confect untouched, so
- * the middleware could not actually cover it, and skipping it would be a
- * policy hole.
+ * A matching-type Convex-provenance function is rejected rather than silently
+ * skipped: its raw handler passes through Confect untouched, so the middleware
+ * could not actually cover it, and skipping it would be a policy hole.
  */
 export type ValidateFunction<
   FunctionSpec_ extends FunctionSpec.AnyWithProps,
@@ -295,8 +297,8 @@ export type ValidateFunction<
   : never;
 
 /**
- * Attachment order is chain order, so requiring `requires` to be satisfied
- * by already-attached middleware is exactly requiring the provider to run
+ * Attachment order is chain order, so requiring `requires` to be satisfied by
+ * already-attached middleware is exactly requiring the provider to run
  * earlier.
  */
 export type ValidateAttach<
@@ -344,14 +346,14 @@ type GroupOverlap<
     : never;
 
 /**
- * The parameter-type validation applied to the group spec at
- * `GroupImpl.make`: every function's attached middleware must have its
- * `requires` services provided by some middleware covering that function
- * (the group's or the function's own). Checked here—with the group fully
- * assembled—rather than at the spec builders, because a function-level
- * middleware's `requires` may legitimately be satisfied by a group
- * middleware the function spec never sees, and group attachment is
- * declaratively order-independent with respect to `addFunction`.
+ * The parameter-type validation applied to the group spec at `GroupImpl.make`:
+ * every function's attached middleware must have its `requires` services
+ * provided by some middleware covering that function (the group's or the
+ * function's own). Checked here—with the group fully assembled—rather than at
+ * the spec builders, because a function-level middleware's `requires` may
+ * legitimately be satisfied by a group middleware the function spec never sees,
+ * and group attachment is declaratively order-independent with respect to
+ * `addFunction`.
  */
 export type ValidateImplRequires<
   Functions_ extends FunctionSpec.AnyWithProps,

package/src/PaginationError.ts

@@ -4,7 +4,9 @@ import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
-/** A Convex pagination cursor that no longer describes the current query. */
+/**
+ * A Convex pagination cursor that no longer describes the current query.
+ */
 export class InvalidCursor extends Schema.TaggedError<InvalidCursor>()(
   "InvalidCursor",
   {
@@ -40,7 +42,9 @@ const fromErrorMessage = (
     ? Option.some(new InvalidCursor({ cause: error }))
     : Option.none();
 
-/** Recognizes an invalid-cursor error emitted by a Convex query. */
+/**
+ * Recognizes an invalid-cursor error emitted by a Convex query.
+ */
 export const fromConvexQueryError = (
   error: unknown,
 ): Option.Option<InvalidCursor> =>
@@ -59,7 +63,9 @@ export const fromConvexQueryError = (
     Match.exhaustive,
   );
 
-/** Recognizes the error data attached to Convex's invalid-cursor error. */
+/**
+ * Recognizes the error data attached to Convex's invalid-cursor error.
+ */
 export const fromConvexErrorData = (
   errorData: unknown,
 ): Option.Option<InvalidCursor> =>

package/src/PaginationOptions.ts

@@ -1,8 +1,8 @@
 import * as Schema from "effect/Schema";
 
 /**
- * Schema for the `paginationOpts` argument that every paginated query
- * receives. Mirrors `paginationOptsValidator` from `convex/server`.
+ * Schema for the `paginationOpts` argument that every paginated query receives.
+ * Mirrors `paginationOptsValidator` from `convex/server`.
  *
  * Use this as the `paginationOpts` field of a paginated query's args schema.
  * Beyond `numItems` and `cursor`, Convex's pagination protocol sends the

package/src/Ref.ts

@@ -36,8 +36,8 @@ export interface Base<
 
 /**
  * A reference to a single Convex function, as callers see it: the wire name
- * plus the data needed to encode args, decode returns, and decode typed
- * errors. A ref is one of two shapes, keyed by the spec's provenance.
+ * plus the data needed to encode args, decode returns, and decode typed errors.
+ * A ref is one of two shapes, keyed by the spec's provenance.
  */
 export type Ref<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -81,8 +81,8 @@ export type ConfectRef<
 /**
  * Internal form used while mapping a spec to a ref. Supplying the already
  * derived value types avoids repeatedly expanding `Schema.Struct` for every
- * leaf in a generated ref tree; the public `ConfectRef` alias still derives
- * the same values from its fields and schemas.
+ * leaf in a generated ref tree; the public `ConfectRef` alias still derives the
+ * same values from its fields and schemas.
  */
 interface ConfectRefWithTypes<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -125,7 +125,9 @@ export interface ConvexRef<
 
 export type Any = Ref<any, any, any, any, any>;
 
-/** Erased Confect-provenance ref used by provenance-specific APIs. */
+/**
+ * Erased Confect-provenance ref used by provenance-specific APIs.
+ */
 export type AnyConfect = Extract<Any, { readonly _tag: "Confect" }>;
 
 export type AnyInternal = Ref<any, "internal", any, any, any>;
@@ -228,7 +230,9 @@ export type Args<Ref_> = Ref_ extends { readonly "~Args": infer Args_ }
   ? Args_
   : never;
 
-/** The field map captured by a Confect-provenance ref. */
+/**
+ * The field map captured by a Confect-provenance ref.
+ */
 export type ArgsFields<Ref_> = Ref_ extends {
   readonly _tag: "Confect";
   readonly args: {
@@ -238,7 +242,9 @@ export type ArgsFields<Ref_> = Ref_ extends {
   ? ArgsFields_
   : never;
 
-/** The assembled args schema carried by a Confect-provenance ref. */
+/**
+ * The assembled args schema carried by a Confect-provenance ref.
+ */
 export type ArgsSchema<Ref_> = Ref_ extends {
   readonly _tag: "Confect";
   readonly args: infer ArgsSchema_ extends FunctionProvenance.AnyArgsSchema;
@@ -481,11 +487,11 @@ export const isConvexError = (error: unknown): error is ConvexError<Value> =>
 /**
  * Build a callback-style handler that decodes the ref's typed error from a
  * caught `ConvexError`, or else forwards the value to `mapUnknownError`. The
- * fallback is also invoked when the input *is* a `ConvexError` but the ref
- * doesn't declare a typed-error schema—by definition such a value falls
- * outside the ref's error contract. Useful when adapting non-Effect APIs (e.g.
- * emitter callbacks for streamed subscriptions) to the same error semantics
- * that `runWithCodec` provides.
+ * fallback is also invoked when the input _is_ a `ConvexError` but the ref
+ * doesn't declare a typed-error schema—by definition such a value falls outside
+ * the ref's error contract. Useful when adapting non-Effect APIs (e.g. emitter
+ * callbacks for streamed subscriptions) to the same error semantics that
+ * `runWithCodec` provides.
  */
 export const decodeErrorOrElse =
   <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) =>
@@ -519,13 +525,13 @@ const errorSchemaOf = (ref: Any): Option.Option<Schema.Codec<any, any>> =>
   );
 
 /**
- * Decode `encodedError` against the ref's error schema—the function's
- * declared `error` schema unioned with its covering middlewares' error
- * schemas. Returns `None` if the ref declares no typed error at all (Confect
- * ref without an `error` schema and without failing middleware, or a
- * Convex-provenance ref)—by definition there's nothing to decode the value
- * into, and the caller is responsible for deciding what to do (typically:
- * surface the original value as a defect).
+ * Decode `encodedError` against the ref's error schema—the function's declared
+ * `error` schema unioned with its covering middlewares' error schemas. Returns
+ * `None` if the ref declares no typed error at all (Confect ref without an
+ * `error` schema and without failing middleware, or a Convex-provenance ref)—by
+ * definition there's nothing to decode the value into, and the caller is
+ * responsible for deciding what to do (typically: surface the original value as
+ * a defect).
  */
 export const decodeError = <Ref_ extends Any>(
   ref: Ref_,
@@ -541,18 +547,17 @@ export const decodeError = <Ref_ extends Any>(
 
 /**
  * Synchronous counterpart to `decodeError`. Returns `None` when the value is
- * not this ref's typed error—either because the ref declares no `error`
- * schema, or because `encodedError` doesn't match the one it declares.
+ * not this ref's typed error—either because the ref declares no `error` schema,
+ * or because `encodedError` doesn't match the one it declares.
  *
  * The second case is reachable in normal operation: Convex raises its own
- * `ConvexError`s (an `InvalidCursor` pagination error, for instance), and
- * those never match a user-declared error schema. Callers pair this with a
- * fallback that surfaces the original error, so failing to decode must not
- * throw—a `ParseError` here would replace the real error with an opaque one
- * and lose the only useful diagnostic. Hence the `Option` suffix rather than
- * `Sync`, matching `Schema.decodeUnknownOption`: the sibling `*Sync` helpers
- * in this module all throw on a parse failure, and this one deliberately
- * doesn't.
+ * `ConvexError`s (an `InvalidCursor` pagination error, for instance), and those
+ * never match a user-declared error schema. Callers pair this with a fallback
+ * that surfaces the original error, so failing to decode must not throw—a
+ * `ParseError` here would replace the real error with an opaque one and lose
+ * the only useful diagnostic. Hence the `Option` suffix rather than `Sync`,
+ * matching `Schema.decodeUnknownOption`: the sibling `*Sync` helpers in this
+ * module all throw on a parse failure, and this one deliberately doesn't.
  */
 export const decodeErrorOption = <Ref_ extends Any>(
   ref: Ref_,
@@ -589,10 +594,11 @@ const paginatedKind = (ref: AnyConfect): FunctionProvenance.Paginated =>
   );
 
 /**
- * Encode the args of a paginated query ref via its user-args schema—`paginationOpts` is excluded, since the pagination protocol fields are
+ * Encode the args of a paginated query ref via its user-args
+ * schema—`paginationOpts` is excluded, since the pagination protocol fields are
  * managed by the client (e.g. `usePaginatedQuery` from `convex/react`), not by
- * the caller. Requires a ref built with `FunctionSpec.publicPaginatedQuery`
- * (or `internalPaginatedQuery`).
+ * the caller. Requires a ref built with `FunctionSpec.publicPaginatedQuery` (or
+ * `internalPaginatedQuery`).
  */
 export const encodePaginatedQueryArgsSync = <
   Ref_ extends AnyPublicPaginatedQuery,

package/src/Refs.ts

@@ -6,7 +6,7 @@ import type * as FunctionSpec from "./FunctionSpec";
 import type * as GroupSpec from "./GroupSpec";
 import type * as MiddlewareSpec from "./MiddlewareSpec";
 import * as Ref from "./Ref";
-import type * as Spec from "./Spec";
+import * as Spec from "./Spec";
 
 export type Refs<
   Spec_ extends Spec.AnyWithProps,
@@ -98,7 +98,7 @@ type Any =
 export const make = <Spec_ extends Spec.AnyWithProps>(
   spec: Spec_,
 ): FromSpec<Spec_> => {
-  const refs = makeHelper(spec.groups);
+  const refs = makeHelper(Spec.groups(spec));
   return {
     public: refs as Refs<Spec_, Ref.AnyPublic>,
     internal: refs as Refs<Spec_, Ref.AnyInternal>,

package/src/Spec.ts

@@ -1,5 +1,6 @@
 import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
+import * as Struct from "effect/Struct";
 import * as GroupSpec from "./GroupSpec";
 
 export const TypeId = "~@confect/core/Spec";
@@ -15,61 +16,71 @@ export const isSpec = (u: unknown): u is AnyWithProps =>
  * group lives on the group itself (`GroupSpec.runtime`) and on each function's
  * `RuntimeAndFunctionType`; the spec does not carry a runtime of its own.
  */
-export interface Spec<Groups_ extends GroupSpec.AnyWithProps = never> {
-  readonly [TypeId]: TypeId;
-  readonly groups: {
-    [GroupName in GroupSpec.Name<Groups_>]: GroupSpec.WithName<
-      Groups_,
-      GroupName
-    >;
-  };
-  readonly "~Groups": Groups_;
+export interface Spec<
+  Groups_ extends Record.ReadonlyRecord<string, GroupSpec.AnyWithProps> = {},
+> {
+  readonly [TypeId]: Readonly<Groups_>;
 
   add<Group extends GroupSpec.AnyWithProps>(
     group: Group,
-  ): Spec<Groups_ | Group>;
+  ): Spec<
+    Struct.Assign<Groups_, Record.ReadonlyRecord<GroupSpec.Name<Group>, Group>>
+  >;
 
   addAt<const Name extends string, Group extends GroupSpec.AnyWithProps>(
     name: Name,
     group: Group,
-  ): Spec<Groups_ | GroupSpec.NamedAt<Group, Name>>;
+  ): Spec<
+    Struct.Assign<
+      Groups_,
+      Record.ReadonlyRecord<Name, GroupSpec.NamedAt<Group, Name>>
+    >
+  >;
 }
 
 export interface Any {
-  readonly [TypeId]: TypeId;
+  readonly [TypeId]: unknown;
 }
 
-export interface AnyWithProps extends Spec<GroupSpec.AnyWithProps> {}
+export interface AnyWithProps extends Any {
+  readonly [TypeId]: Record.ReadonlyRecord<string, GroupSpec.AnyWithProps>;
+}
 
-export type Groups<Spec_ extends AnyWithProps> = Spec_["~Groups"];
+export type Groups<Spec_ extends AnyWithProps> =
+  Spec_[TypeId][keyof Spec_[TypeId]];
 
-const Proto = {
-  [TypeId]: TypeId,
+/**
+ * The group record stored by a spec, with its precise member types.
+ */
+export const groups = <Spec_ extends AnyWithProps>(
+  self: Spec_,
+): Spec_[TypeId] => self[TypeId];
 
-  add<Group extends GroupSpec.AnyWithProps>(this: AnyWithProps, group: Group) {
-    return makeProto({
-      groups: Record.set(this.groups, group.name, group),
-    });
+const makeRecord = <
+  Groups_ extends Record.ReadonlyRecord<string, GroupSpec.AnyWithProps>,
+>(
+  record: Groups_,
+): Spec<Groups_> => ({
+  [TypeId]: record,
+  add<Group extends GroupSpec.AnyWithProps>(group: Group) {
+    return makeRecord(
+      Struct.assign(
+        record,
+        Record.singleton<GroupSpec.Name<Group>, Group>(group.name, group),
+      ),
+    );
   },
-
-  addAt<Group extends GroupSpec.AnyWithProps>(
-    this: AnyWithProps,
-    name: string,
+  addAt<const Name extends string, Group extends GroupSpec.AnyWithProps>(
+    name: Name,
     group: Group,
   ) {
-    return makeProto({
-      groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),
-    });
+    return makeRecord(
+      Struct.assign(
+        record,
+        Record.singleton(name, GroupSpec.withName(name, group)),
+      ),
+    );
   },
-};
-
-const makeProto = <Groups_ extends GroupSpec.AnyWithProps>({
-  groups,
-}: {
-  groups: Record.ReadonlyRecord<string, Groups_>;
-}): Spec<Groups_> =>
-  Object.assign(Object.create(Proto), {
-    groups,
-  }) as Spec<Groups_>;
+});
 
-export const make = (): Spec => makeProto({ groups: {} });
+export const make = (): Spec => makeRecord({});

package/src/SystemFields.ts

@@ -13,7 +13,8 @@ import * as Struct from "effect/Struct";
 import * as GenericId from "./GenericId";
 
 /**
- * Produces a schema for Convex system fields. In Confect, system fields include `_id`.
+ * Produces a schema for Convex system fields. In Confect, system fields include
+ * `_id`.
  */
 export const SystemFields = <TableName extends string>(tableName: TableName) =>
   Schema.Struct({
@@ -61,20 +62,18 @@ const splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {
 const wrapGetter = <R>(
   getter: SchemaGetter.Getter<any, any, R>,
 ): SchemaGetter.Getter<any, any, R> =>
-  new SchemaGetter.Getter((input, options) => {
+  SchemaGetter.transformOptionalEffect((input, options) => {
     if (Option.isNone(input) || !Predicate.isObject(input.value)) {
-      return getter.run(input, options);
+      return SchemaGetter.run(getter, input, options);
     }
     const { system, rest } = splitSystemFields(input.value);
-    return getter
-      .run(Option.some(rest), options)
-      .pipe(
-        Effect.map(
-          Option.map((output) =>
-            Predicate.isObject(output) ? Struct.assign(output, system) : output,
-          ),
+    return SchemaGetter.run(getter, Option.some(rest), options).pipe(
+      Effect.map(
+        Option.map((output) =>
+          Predicate.isObject(output) ? Struct.assign(output, system) : output,
         ),
-      );
+      ),
+    );
   });
 
 const wrapTransformation = (
@@ -154,10 +153,11 @@ const makeExtendAst = (
 /**
  * Extend a table schema with Convex system fields.
  *
- * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union`
- * has them distributed across its members, preserving the schema's
- * `Struct`/`Union` structure. Any other object-shaped schema—one built with
- * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended schema—is extended at the AST level: every object node in its encoding chain
+ * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union` has
+ * them distributed across its members, preserving the schema's `Struct`/`Union`
+ * structure. Any other object-shaped schema—one built with
+ * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended
+ * schema—is extended at the AST level: every object node in its encoding chain
  * gains the system fields, and each transformation is wrapped so the fields
  * bypass the user-defined getters. Schemas that do not resolve to an object
  * shape at every step (such as `Schema.Class`, whose decoded values are class
@@ -218,9 +218,9 @@ export const extendWithSystemFields = <
 };
 
 /**
- * Applies the system fields to a single struct, mirroring `Schema.fieldsAssign`.
- * Any other (already-extended or opaque) schema falls back to a `Codec` carrying
- * the system-field document shape.
+ * Applies the system fields to a single struct, mirroring
+ * `Schema.fieldsAssign`. Any other (already-extended or opaque) schema falls
+ * back to a `Codec` carrying the system-field document shape.
  */
 type ApplySystemFields<TableName extends string, S> =
   S extends Schema.Struct<infer Fields extends Schema.Struct.Fields>
@@ -240,10 +240,10 @@ type ApplySystemFields<TableName extends string, S> =
  * This mirrors the runtime {@link extendWithSystemFields}: a `Struct` gains the
  * system fields directly (matching `Schema.fieldsAssign`), and a `Union` has
  * them distributed across its members (matching
- * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The `Struct`/`Union`
- * structure is preserved rather than collapsed to a bare `Codec`; any other
- * schema falls back to a `Codec` carrying the system-field document shape,
- * matching the runtime's AST-level extension.
+ * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The
+ * `Struct`/`Union` structure is preserved rather than collapsed to a bare
+ * `Codec`; any other schema falls back to a `Codec` carrying the system-field
+ * document shape, matching the runtime's AST-level extension.
  */
 export type ExtendWithSystemFields<
   TableName extends string,

package/src/Table.ts

@@ -417,6 +417,7 @@ export const make = <const TableSchema_ extends Schema.Codec<any, any>>(
  * Extract all of the index field paths within a Convex `Validator`.
  *
  * This is used when declaring table indexes.
+ *
  * @public
  */
 type ExtractFieldPaths<T extends Validator<any, any, any>> =