@confect/server 7.0.0 → 9.0.0-next.0

package/src/DatabaseSchema.ts

@@ -9,7 +9,11 @@ import * as Table from "./Table";
 export const TypeId = "@confect/server/DatabaseSchema";
 export type TypeId = typeof TypeId;
 
-export const isSchema = (u: unknown): u is Any =>
+export interface Any {
+  readonly [TypeId]: TypeId;
+}
+
+export const isDatabaseSchema = (u: unknown): u is Any =>
   Predicate.hasProperty(u, TypeId);
 
 /**
@@ -31,10 +35,6 @@ export interface DatabaseSchema<Tables_ extends Table.AnyWithProps = never> {
   ): DatabaseSchema<Tables_ | TableDef>;
 }
 
-export interface Any {
-  readonly [TypeId]: TypeId;
-}
-
 export interface AnyWithProps {
   readonly [TypeId]: TypeId;
   readonly tables: Record<string, Table.AnyWithProps>;

package/src/Document.ts

@@ -1,6 +1,6 @@
+import * as SystemFields from "@confect/core/SystemFields";
 import { Effect, Function, ParseResult, pipe, Schema } from "effect";
 import type { ReadonlyRecord } from "effect/Record";
-import * as SystemFields from "@confect/core/SystemFields";
 import type * as DataModel from "./DataModel";
 import type { ReadonlyValue } from "./SchemaToValidator";
 import type * as TableInfo from "./TableInfo";
@@ -10,6 +10,37 @@ export type WithoutSystemFields<Doc> = Omit<Doc, "_creationTime" | "_id">;
 export type Any = any;
 export type AnyEncoded = ReadonlyRecord<string, ReadonlyValue>;
 
+type Decode = (doc: unknown) => Effect.Effect<unknown, ParseResult.ParseError>;
+
+const decoderCache = new WeakMap<
+  Schema.Schema.AnyNoContext,
+  Map<string, Decode>
+>();
+
+const getDecoder = (
+  tableName: string,
+  tableSchema: Schema.Schema.AnyNoContext,
+): Decode => {
+  const byTable =
+    decoderCache.get(tableSchema) ??
+    (() => {
+      const map = new Map<string, Decode>();
+      decoderCache.set(tableSchema, map);
+      return map;
+    })();
+
+  return (
+    byTable.get(tableName) ??
+    (() => {
+      const decoder = Schema.decode(
+        SystemFields.extendWithSystemFields(tableName, tableSchema),
+      ) as Decode;
+      byTable.set(tableName, decoder);
+      return decoder;
+    })()
+  );
+};
+
 export const decode = Function.dual<
   <
     DataModel_ extends DataModel.AnyWithProps,
@@ -53,36 +84,43 @@ export const decode = Function.dual<
     DataModel.TableInfoWithName_<DataModel_, TableName>["document"],
     DocumentDecodeError
   > =>
-    Effect.gen(function* () {
-      const TableSchemaWithSystemFields = SystemFields.extendWithSystemFields(
-        tableName,
-        tableSchema,
-      );
-
-      const encodedDoc =
-        self as (typeof TableSchemaWithSystemFields)["Encoded"];
-
-      const decodedDoc = yield* pipe(
-        encodedDoc,
-        Schema.decode(TableSchemaWithSystemFields),
-        Effect.catchTag("ParseError", (parseError) =>
-          Effect.gen(function* () {
-            const formattedParseError =
-              yield* ParseResult.TreeFormatter.formatError(parseError);
-
-            return yield* new DocumentDecodeError({
-              tableName,
-              id: encodedDoc._id,
-              parseError: formattedParseError,
-            });
-          }),
-        ),
-      );
-
-      return decodedDoc;
-    }),
+    pipe(
+      self,
+      getDecoder(tableName, tableSchema),
+      Effect.catchIf(ParseResult.isParseError, (parseError) =>
+        Effect.gen(function* () {
+          const formattedParseError =
+            yield* ParseResult.TreeFormatter.formatError(parseError);
+
+          return yield* new DocumentDecodeError({
+            tableName,
+            id: self._id,
+            parseError: formattedParseError,
+          });
+        }),
+      ),
+      Effect.map(
+        (decodedDoc) =>
+          decodedDoc as DataModel.TableInfoWithName_<
+            DataModel_,
+            TableName
+          >["document"],
+      ),
+    ),
 );
 
+type Encode = (doc: unknown) => Effect.Effect<unknown, ParseResult.ParseError>;
+
+const encoderCache = new WeakMap<Schema.Schema.AnyNoContext, Encode>();
+
+const getEncoder = (tableSchema: Schema.Schema.AnyNoContext): Encode =>
+  encoderCache.get(tableSchema) ??
+  (() => {
+    const encoder = Schema.encode(tableSchema) as Encode;
+    encoderCache.set(tableSchema, encoder);
+    return encoder;
+  })();
+
 export const encode = Function.dual<
   <
     DataModel_ extends DataModel.AnyWithProps,
@@ -126,35 +164,29 @@ export const encode = Function.dual<
     DataModel.TableInfoWithName_<DataModel_, TableName>["encodedDocument"],
     DocumentEncodeError
   > =>
-    Effect.gen(function* () {
-      type TableSchemaWithSystemFields = SystemFields.ExtendWithSystemFields<
-        TableName,
-        TableInfo.TableSchema<
-          DataModel.TableInfoWithName_<DataModel_, TableName>
-        >
-      >;
-
-      const decodedDoc = self as TableSchemaWithSystemFields["Type"];
-
-      const encodedDoc = yield* pipe(
-        decodedDoc,
-        Schema.encode(tableSchema),
-        Effect.catchTag("ParseError", (parseError) =>
-          Effect.gen(function* () {
-            const formattedParseError =
-              yield* ParseResult.TreeFormatter.formatError(parseError);
-
-            return yield* new DocumentEncodeError({
-              tableName,
-              id: decodedDoc._id,
-              parseError: formattedParseError,
-            });
-          }),
-        ),
-      );
-
-      return encodedDoc;
-    }),
+    pipe(
+      self,
+      getEncoder(tableSchema),
+      Effect.catchIf(ParseResult.isParseError, (parseError) =>
+        Effect.gen(function* () {
+          const formattedParseError =
+            yield* ParseResult.TreeFormatter.formatError(parseError);
+
+          return yield* new DocumentEncodeError({
+            tableName,
+            id: self._id,
+            parseError: formattedParseError,
+          });
+        }),
+      ),
+      Effect.map(
+        (encodedDoc) =>
+          encodedDoc as DataModel.TableInfoWithName_<
+            DataModel_,
+            TableName
+          >["encodedDocument"],
+      ),
+    ),
 );
 
 export class DocumentDecodeError extends Schema.TaggedError<DocumentDecodeError>()(

package/src/FunctionImpl.ts

@@ -1,11 +1,11 @@
 import type * as FunctionSpec from "@confect/core/FunctionSpec";
-import type * as GroupPath from "@confect/core/GroupPath";
 import type * as GroupSpec from "@confect/core/GroupSpec";
-import { Array, Context, Effect, Layer, Ref, String } from "effect";
+import * as Registry from "@confect/core/Registry";
+import { Context, Effect, Layer, Ref, String } from "effect";
 import type * as Api from "./Api";
+import { resolveGroupPathUnsafe } from "./GroupPath";
 import type * as Handler from "./Handler";
 import { setNestedProperty } from "./internal/utils";
-import * as Registry from "./Registry";
 import * as RegistryItem from "./RegistryItem";
 
 export interface FunctionImpl<
@@ -32,34 +32,23 @@ export const FunctionImpl = <
 
 export const make = <
   Api_ extends Api.AnyWithProps,
-  const GroupPath_ extends GroupPath.All<Api.Groups<Api_>>,
-  const FunctionName extends FunctionSpec.Name<
-    GroupSpec.Functions<GroupPath.GroupAt<Api.Groups<Api_>, GroupPath_>>
-  >,
+  Group extends GroupSpec.AnyWithProps,
+  const FunctionName extends FunctionSpec.Name<GroupSpec.Functions<Group>>,
 >(
   api: Api_,
-  groupPath: GroupPath_,
+  group: Group,
   functionName: FunctionName,
   handler: Handler.WithName<
     Api.Schema<Api_>,
-    GroupSpec.Functions<GroupPath.GroupAt<Api.Groups<Api_>, GroupPath_>>,
+    GroupSpec.Functions<Group>,
     FunctionName
   >,
-): Layer.Layer<FunctionImpl<GroupPath_, FunctionName>> => {
-  const groupPathParts = String.split(groupPath, ".");
-  const [firstGroupPathPart, ...restGroupPathParts] = groupPathParts;
-
-  const group_: GroupSpec.AnyWithProps = Array.reduce(
-    restGroupPathParts,
-    (api as any).spec.groups[firstGroupPathPart as any]!,
-    (currentGroup: any, groupPathPart: any) =>
-      currentGroup.groups[groupPathPart],
-  );
-
-  const functionSpec = group_.functions[functionName]!;
+): Layer.Layer<FunctionImpl<string, FunctionName>> => {
+  const groupPath = resolveGroupPathUnsafe(api.spec, group);
+  const functionSpec = group.functions[functionName]!;
 
   return Layer.effect(
-    FunctionImpl<GroupPath_, FunctionName>({
+    FunctionImpl<string, FunctionName>({
       groupPath,
       functionName,
     }),
@@ -69,7 +58,7 @@ export const make = <
       yield* Ref.update(registry, (registryItems) =>
         setNestedProperty(
           registryItems,
-          [...groupPathParts, functionName],
+          [...String.split(groupPath, "."), functionName],
           RegistryItem.make({
             functionSpec,
             handler,
@@ -94,19 +83,21 @@ export type ForGroupPathAndFunction<
 > = FunctionImpl<GroupPath_, FunctionName>;
 
 /**
- * Get all function implementation services required for a group at a given path.
+ * Get all function implementation services required for a group spec.
  */
-export type FromGroupAtPath<
-  GroupPath_ extends string,
-  Group extends GroupSpec.AnyWithProps,
-> =
-  GroupPath.GroupAt<Group, GroupPath_> extends infer GroupAtPath extends
-    GroupSpec.AnyWithProps
-    ? FunctionSpec.Name<
-        GroupSpec.Functions<GroupAtPath>
-      > extends infer FunctionNames extends string
-      ? FunctionNames extends string
-        ? FunctionImpl<GroupPath_, FunctionNames>
-        : never
+export type FromGroupSpec<Group extends GroupSpec.AnyWithProps> =
+  FunctionSpec.Name<
+    GroupSpec.Functions<Group>
+  > extends infer FunctionNames extends string
+    ? FunctionNames extends string
+      ? FunctionImpl<string, FunctionNames>
       : never
     : never;
+
+/**
+ * @deprecated Use {@link FromGroupSpec} instead.
+ */
+export type FromGroupAtPath<
+  _GroupPath extends string,
+  Group extends GroupSpec.AnyWithProps,
+> = FromGroupSpec<Group>;

package/src/GroupImpl.ts

@@ -1,60 +1,196 @@
-import type * as GroupPath from "@confect/core/GroupPath";
 import type * as GroupSpec from "@confect/core/GroupSpec";
-import { Context, Layer } from "effect";
+import * as Registry from "@confect/core/Registry";
+import {
+  Array,
+  Context,
+  Effect,
+  Layer,
+  Option,
+  pipe,
+  Predicate,
+  Record,
+  Ref,
+  String,
+} from "effect";
 import type * as Api from "./Api";
 import type * as FunctionImpl from "./FunctionImpl";
+import { resolveGroupPathUnsafe } from "./GroupPath";
 
-export interface GroupImpl<GroupPath_ extends string> {
+export const TypeId = "@confect/server/GroupImpl";
+export type TypeId = typeof TypeId;
+
+export type FinalizationStatus = "Unfinalized" | "Finalized";
+
+export interface GroupImpl<
+  GroupPath_ extends string,
+  FinalizationStatus_ extends FinalizationStatus = "Unfinalized",
+> {
+  readonly [TypeId]: TypeId;
   readonly groupPath: GroupPath_;
+  readonly finalizationStatus: FinalizationStatus_;
+  /**
+   * Names of every function registered into this group's layer scope by
+   * `FunctionImpl.make`. Authoritative only when `finalizationStatus` is
+   * `"Finalized"`; the `"Unfinalized"` value is set to `[]` at `make`-time
+   * since the list is only known once `finalize` snapshots the registry.
+   */
+  readonly registeredFunctionNames: ReadonlyArray<string>;
 }
 
-export const GroupImpl = <GroupPath_ extends string>({
+export interface Any extends GroupImpl<string, FinalizationStatus> {}
+
+export const isGroupImpl = (u: unknown): u is Any =>
+  Predicate.hasProperty(u, TypeId);
+
+export interface AnyFinalized extends GroupImpl<string, "Finalized"> {}
+export interface AnyUnfinalized extends GroupImpl<string, "Unfinalized"> {}
+
+export const isFinalizedGroupImpl = (u: unknown): u is AnyFinalized =>
+  isGroupImpl(u) && u.finalizationStatus === "Finalized";
+
+export const isUnfinalizedGroupImpl = (u: unknown): u is AnyUnfinalized =>
+  isGroupImpl(u) && u.finalizationStatus === "Unfinalized";
+
+/**
+ * Build the runtime tag for a `GroupImpl` service. The finalization status is
+ * embedded in the tag string so that `Unfinalized` and `Finalized` are distinct
+ * services at runtime; consumers of a finalized layer (the server's
+ * `RegisteredFunctions.buildForGroup` and the CLI's `implValidation`) retrieve
+ * the typed `Finalized` service directly rather than scanning the context.
+ */
+export const GroupImpl = <
+  GroupPath_ extends string,
+  FinalizationStatus_ extends FinalizationStatus,
+>({
   groupPath,
+  finalizationStatus,
 }: {
   groupPath: GroupPath_;
+  finalizationStatus: FinalizationStatus_;
 }) =>
-  Context.GenericTag<GroupImpl<GroupPath_>>(
-    `@confect/server/GroupImpl/${groupPath}`,
+  Context.GenericTag<GroupImpl<GroupPath_, FinalizationStatus_>>(
+    `@confect/server/GroupImpl/${finalizationStatus}/${groupPath}`,
   );
 
 export const make = <
   Api_ extends Api.AnyWithProps,
-  const GroupPath_ extends GroupPath.All<Api.Groups<Api_>>,
+  Group extends GroupSpec.AnyWithProps,
 >(
-  _api: Api_,
-  groupPath: GroupPath_,
+  api: Api_,
+  group: Group,
 ): Layer.Layer<
-  GroupImpl<GroupPath_>,
+  GroupImpl<string, "Unfinalized">,
   never,
-  | FromGroupWithPath<GroupPath_, Api.Groups<Api_>>
-  | FunctionImpl.FromGroupAtPath<GroupPath_, Api.Groups<Api_>>
-> =>
-  Layer.succeed(
-    GroupImpl<GroupPath_>({
+  FunctionImpl.FromGroupSpec<Group>
+> => {
+  const groupPath = resolveGroupPathUnsafe(api.spec, group);
+
+  return Layer.succeed(
+    GroupImpl<string, "Unfinalized">({
       groupPath,
+      finalizationStatus: "Unfinalized",
     }),
     {
+      [TypeId]: TypeId,
       groupPath,
+      finalizationStatus: "Unfinalized" as const,
+      registeredFunctionNames: [],
     },
   ) as Layer.Layer<
-    GroupImpl<GroupPath_>,
+    GroupImpl<string, "Unfinalized">,
     never,
-    | FromGroupWithPath<GroupPath_, Api.Groups<Api_>>
-    | FunctionImpl.FromGroupAtPath<GroupPath_, Api.Groups<Api_>>
+    FunctionImpl.FromGroupSpec<Group>
   >;
+};
 
-export type FromGroups<Groups extends GroupSpec.Any> = Groups extends never
-  ? never
-  : Groups extends GroupSpec.AnyWithProps
-    ? GroupImpl<GroupSpec.Name<Groups>>
-    : never;
+const isFunctionShaped = (value: unknown): boolean =>
+  Predicate.isRecord(value) && "functionSpec" in value;
 
-export type FromGroupWithPath<
-  GroupPath_ extends string,
-  Group extends GroupSpec.AnyWithProps,
-> =
-  GroupPath.SubGroupsAt<Group, GroupPath_> extends infer SubGroupPaths
-    ? SubGroupPaths extends string
-      ? GroupImpl<SubGroupPaths>
-      : never
-    : never;
+/**
+ * Walk a `RegistryItems` tree to the entries at `groupPath` and return the
+ * names of the function-shaped leaves directly underneath.
+ */
+const collectFunctionNamesAtPath = (
+  items: Registry.RegistryItems,
+  groupPath: string,
+): ReadonlyArray<string> =>
+  pipe(
+    String.split(groupPath, "."),
+    Array.reduce(Option.some<unknown>(items), (acc, segment) =>
+      acc.pipe(
+        Option.filter(Predicate.isRecord),
+        Option.flatMap((node) =>
+          segment in node ? Option.some(node[segment]) : Option.none(),
+        ),
+      ),
+    ),
+    Option.filter(Predicate.isRecord),
+    Option.map(Record.toEntries),
+    Option.map(
+      Array.filterMap(([name, value]) =>
+        isFunctionShaped(value) ? Option.some(name) : Option.none(),
+      ),
+    ),
+    Option.getOrElse((): ReadonlyArray<string> => []),
+  );
+
+const findUnfinalizedGroupImpl = <S>(
+  context: Context.Context<S>,
+): Option.Option<AnyUnfinalized> =>
+  Array.findFirst(context.unsafeMap.values(), isUnfinalizedGroupImpl);
+
+/**
+ * Mark a `GroupImpl` layer as fully implemented. The parameter type defaults
+ * `RIn = never`, so passing a layer that still requires any `FunctionImpl`
+ * service produces a type error at the impl author's site. The codegen
+ * boundary requires the resulting `"Finalized"` brand, so omitting this call
+ * is also rejected downstream.
+ *
+ * As a side effect of finalization, the names of every `FunctionImpl` that
+ * registered into this group's scope are snapshotted onto the produced
+ * service value's `registeredFunctionNames` field, so consumers can verify
+ * impl completeness against a `GroupSpec`'s expected functions without
+ * having to inspect the `Registry` themselves.
+ */
+export const finalize = <GroupPath_ extends string>(
+  group: Layer.Layer<GroupImpl<GroupPath_, "Unfinalized">>,
+): Layer.Layer<GroupImpl<GroupPath_, "Finalized">> =>
+  Layer.flatMap(
+    group,
+    (context): Layer.Layer<GroupImpl<GroupPath_, "Finalized">> =>
+      findUnfinalizedGroupImpl(context).pipe(
+        Option.match({
+          onNone: () =>
+            Layer.die(
+              new Error(
+                "GroupImpl.finalize: no Unfinalized GroupImpl service was found in the layer's context.",
+              ),
+            ),
+          onSome: (unfinalized) => {
+            const groupPath = unfinalized.groupPath as GroupPath_;
+            return Layer.effect(
+              GroupImpl<GroupPath_, "Finalized">({
+                groupPath,
+                finalizationStatus: "Finalized",
+              }),
+              Effect.gen(function* () {
+                const registry = yield* Registry.Registry;
+                const items = yield* Ref.get(registry);
+                return {
+                  [TypeId]: TypeId,
+                  groupPath,
+                  finalizationStatus: "Finalized" as const,
+                  registeredFunctionNames: collectFunctionNamesAtPath(
+                    items,
+                    groupPath,
+                  ),
+                };
+              }),
+            );
+          },
+        }),
+      ),
+  );
+
+export type FromGroupSpec<Group extends GroupSpec.AnyWithProps> =
+  FunctionImpl.FromGroupSpec<Group>;

package/src/GroupPath.ts

@@ -0,0 +1,43 @@
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import type * as Spec from "@confect/core/Spec";
+import { Array, Option, pipe, Record } from "effect";
+
+const resolveGroupPathInGroup = (
+  group: GroupSpec.AnyWithProps,
+  target: GroupSpec.AnyWithProps,
+  pathSegments: ReadonlyArray<string>,
+): Option.Option<string> =>
+  pipe(
+    Record.toEntries(group.groups),
+    Array.findFirst(([name, child]) =>
+      child === target
+        ? Option.some(Array.join([...pathSegments, name], "."))
+        : resolveGroupPathInGroup(child, target, [...pathSegments, name]),
+    ),
+  );
+
+const resolveGroupPath = (
+  spec: Spec.AnyWithProps,
+  target: GroupSpec.AnyWithProps,
+): Option.Option<string> =>
+  pipe(
+    Record.toEntries(spec.groups),
+    Array.findFirst(([name, group]) =>
+      group === target
+        ? Option.some(name)
+        : resolveGroupPathInGroup(group, target, [name]),
+    ),
+  );
+
+export const resolveGroupPathUnsafe = (
+  spec: Spec.AnyWithProps,
+  target: GroupSpec.AnyWithProps,
+): string =>
+  resolveGroupPath(spec, target).pipe(
+    Option.getOrThrowWith(
+      () =>
+        new Error(
+          "Could not resolve group path for the provided GroupSpec. Ensure the spec is part of the assembled API spec tree.",
+        ),
+    ),
+  );

package/src/RegisteredConvexFunction.ts

@@ -98,27 +98,28 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Convex">>(
     Match.exhaustive,
   );
 
-// Convex's query cache is invalidated by any Date.now() call during handler
-// execution. Effect's unsafeFork calls Date.now() when constructing a
-// FiberId.Runtime, which trips the cache for every confect-wrapped query. We
-// stub Date.now to 0 for the span of the handler; queries are forbidden from
-// relying on real time for correctness anyway.
-//
-// Users who explicitly want the real timestamp can still reach it via Effect's
-// Clock service (Clock.currentTimeMillis/Clock.currentTimeNanos). We provide
-// a Clock layer whose methods close over the *original* Date.now, so opting in
-// to Clock is an opt-in to worse caching—but caching is not broken by default.
+/**
+ * Convex's query cache is invalidated by any Date.now() call during handler
+ * execution. Effect's unsafeFork calls Date.now() when constructing a
+ * FiberId.Runtime, which trips the cache for every confect-wrapped query. We
+ * stub Date.now to 0 for the span of the handler; queries are forbidden from
+ * relying on real time for correctness anyway.
+ *
+ * Users who explicitly want the real timestamp can still reach it via Effect's
+ * Clock service (Clock.currentTimeMillis/Clock.currentTimeNanos). We provide a
+ * Clock whose user-facing Effects call realDateNow (Convex's tracker) directly,
+ * making Clock an explicit opt-in to cache invalidation. The unsafe methods
+ * used internally by Effect (logging, span events, scheduler) return constants
+ * so they never touch the tracker—caching is not broken by default.
+ */
 const unpatchedClock = (realDateNow: () => number): Clock.Clock => {
-  const bigint1e6 = BigInt(1_000_000);
-  const unsafeCurrentTimeMillis = () => realDateNow();
-  const unsafeCurrentTimeNanos = () => BigInt(realDateNow()) * bigint1e6;
   const defaultClock = Clock.make();
   return {
     ...defaultClock,
-    unsafeCurrentTimeMillis,
-    unsafeCurrentTimeNanos,
-    currentTimeMillis: Effect.sync(unsafeCurrentTimeMillis),
-    currentTimeNanos: Effect.sync(unsafeCurrentTimeNanos),
+    unsafeCurrentTimeMillis: () => 0,
+    unsafeCurrentTimeNanos: () => 0n,
+    currentTimeMillis: Effect.sync(() => realDateNow()),
+    currentTimeNanos: Effect.sync(() => BigInt(realDateNow()) * 1_000_000n),
   };
 };