@confect/server 9.0.1 → 9.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@confect/server",
   "description": "Backend bindings to the Convex platform",
-  "version": "9.0.1",
+  "version": "9.1.0",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
@@ -68,7 +68,7 @@
     "@effect/platform-node": "^0.106.0",
     "convex": "^1.32.0",
     "effect": "^3.21.2",
-    "@confect/core": "^9.0.1"
+    "@confect/core": "^9.1.0"
   },
   "peerDependenciesMeta": {
     "@effect/platform-node": {

package/src/ActionCtx.ts

@@ -1,9 +1,15 @@
 import type { GenericActionCtx, GenericDataModel } from "convex/server";
 import * as Context from "effect/Context";
 
-export const ActionCtx = <DataModel extends GenericDataModel>() =>
+export type ActionCtxTag<DataModel extends GenericDataModel> = Context.Tag<
+  GenericActionCtx<DataModel>,
+  GenericActionCtx<DataModel>
+>;
+
+export const ActionCtx = <
+  DataModel extends GenericDataModel,
+>(): ActionCtxTag<DataModel> =>
   Context.GenericTag<GenericActionCtx<DataModel>>("@confect/server/ActionCtx");
 
-export type ActionCtx<DataModel extends GenericDataModel> = ReturnType<
-  typeof ActionCtx<DataModel>
->["Identifier"];
+export type ActionCtx<DataModel extends GenericDataModel> =
+  GenericActionCtx<DataModel>;

package/src/DatabaseReader.ts

@@ -7,17 +7,45 @@ import type * as DataModel from "./DataModel";
 import * as QueryInitializer from "./QueryInitializer";
 import * as Table from "./Table";
 
+type IncludedTables<DatabaseSchema_ extends DatabaseSchema.AnyWithProps> =
+  | DatabaseSchema.Tables<DatabaseSchema_>
+  | Table.SystemTables;
+
+type IncludedDataModel<DatabaseSchema_ extends DatabaseSchema.AnyWithProps> =
+  DataModel.DataModel<IncludedTables<DatabaseSchema_>>;
+
+export interface DatabaseReaderService<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+> {
+  readonly table: <
+    const TableName extends Table.Name<IncludedTables<DatabaseSchema_>>,
+  >(
+    tableName: TableName,
+  ) => QueryInitializer.QueryInitializer<
+    IncludedDataModel<DatabaseSchema_>,
+    TableName,
+    DataModel.TableInfoWithName<IncludedDataModel<DatabaseSchema_>, TableName>,
+    DataModel.TableInfoWithName_<IncludedDataModel<DatabaseSchema_>, TableName>,
+    TableName extends keyof Docs
+      ? Docs[TableName]
+      : DataModel.DocumentWithName<
+          IncludedDataModel<DatabaseSchema_>,
+          TableName
+        >
+  >;
+}
+
 export const make = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,
   convexDatabaseReader: GenericDatabaseReader<
     DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
   >,
-) => {
-  type Tables = DatabaseSchema.Tables<DatabaseSchema_>;
-  type IncludedTables = Tables | Table.SystemTables;
-
+): DatabaseReaderService<DatabaseSchema_> => {
   return {
-    table: <const TableName extends Table.Name<IncludedTables>>(
+    table: <
+      const TableName extends Table.Name<IncludedTables<DatabaseSchema_>>,
+    >(
       tableName: TableName,
     ) => {
       const isSystem = Object.hasOwn(Table.systemTables, tableName);
@@ -38,27 +66,44 @@ export const make = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
               tableName
             ]
           : databaseSchema.tables[tableName]
-      ) as Table.WithName<IncludedTables, TableName>;
+      ) as Table.WithName<IncludedTables<DatabaseSchema_>, TableName>;
 
-      return QueryInitializer.make<IncludedTables, TableName>(
+      return QueryInitializer.make<IncludedTables<DatabaseSchema_>, TableName>(
         tableName,
         baseDatabaseReader,
         table,
       );
     },
-  };
+  } as DatabaseReaderService<DatabaseSchema_>;
 };
 
+/**
+ * The tag's *Identifier* (the Effect requirements-channel type) is
+ * `Docs`-independent so a helper's `R` channel is the same whether or not a
+ * codegen document registry is supplied — this keeps it identical to what
+ * `Handler`/runtime provisioning provide. The tag's *Service* (what `yield*`
+ * produces) carries `Docs`, so queries resolve to the named doc interfaces.
+ */
+export type DatabaseReaderTag<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+> = Context.Tag<
+  DatabaseReaderService<DatabaseSchema_>,
+  DatabaseReaderService<DatabaseSchema_, Docs>
+>;
+
 export const DatabaseReader = <
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
->() =>
-  Context.GenericTag<ReturnType<typeof make<DatabaseSchema_>>>(
-    "@confect/server/DatabaseReader",
-  );
+  Docs = {},
+>(): DatabaseReaderTag<DatabaseSchema_, Docs> =>
+  Context.GenericTag<
+    DatabaseReaderService<DatabaseSchema_>,
+    DatabaseReaderService<DatabaseSchema_, Docs>
+  >("@confect/server/DatabaseReader");
 
 export type DatabaseReader<
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
-> = ReturnType<typeof DatabaseReader<DatabaseSchema_>>["Identifier"];
+> = DatabaseReaderService<DatabaseSchema_>;
 
 export const layer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,

package/src/DatabaseWriter.ts

@@ -19,12 +19,73 @@ import * as QueryInitializer from "./QueryInitializer";
 import type * as Table from "./Table";
 import type * as TableInfo from "./TableInfo";
 
+export interface DatabaseWriterTableAccessor<
+  DataModel_ extends DataModel.AnyWithProps,
+  TableName extends DataModel.TableNames<DataModel_>,
+  Doc = DocumentByName_<DataModel_, TableName>,
+> {
+  readonly insert: (
+    document: Document.WithoutSystemFields<Doc>,
+  ) => Effect.Effect<GenericId<TableName>, Document.DocumentEncodeError>;
+  readonly patch: (
+    id: GenericId<TableName>,
+    patchedValues: Partial<Document.WithoutSystemFields<Doc>>,
+  ) => Effect.Effect<
+    void,
+    | QueryInitializer.GetByIdFailure
+    | Document.DocumentDecodeError
+    | Document.DocumentEncodeError
+  >;
+  readonly replace: (
+    id: GenericId<TableName>,
+    value: Document.WithoutSystemFields<Doc>,
+  ) => Effect.Effect<void, Document.DocumentEncodeError>;
+  readonly delete: (id: GenericId<TableName>) => Effect.Effect<void>;
+}
+
+/**
+ * The service shape backing the `DatabaseWriter` tag. Named (rather than an
+ * inferred anonymous object) so declaration emit prints
+ * `DatabaseWriterService<…>` by reference instead of expanding the data model.
+ * `Docs` is the optional named document registry (see `DatabaseReaderService`).
+ */
+export interface DatabaseWriterService<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+> {
+  readonly table: <
+    const TableName extends DataModel.TableNames<
+      DataModel.FromSchema<DatabaseSchema_>
+    >,
+  >(
+    tableName: TableName,
+  ) => DatabaseWriterTableAccessor<
+    DataModel.FromSchema<DatabaseSchema_>,
+    TableName,
+    TableName extends keyof Docs
+      ? Docs[TableName]
+      : DocumentByName_<DataModel.FromSchema<DatabaseSchema_>, TableName>
+  >;
+}
+
+/**
+ * The tag's *Identifier* is `Docs`-independent (see `DatabaseReaderTag`); only
+ * the *Service* carries `Docs` so writer inputs print the named doc interfaces.
+ */
+export type DatabaseWriterTag<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+> = Context.Tag<
+  DatabaseWriterService<DatabaseSchema_>,
+  DatabaseWriterService<DatabaseSchema_, Docs>
+>;
+
 export const make = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,
   convexDatabaseWriter: GenericDatabaseWriter<
     DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
   >,
-) => {
+): DatabaseWriterService<DatabaseSchema_> => {
   type DataModel_ = DataModel.FromSchema<DatabaseSchema_>;
 
   const table = <const TableName extends DataModel.TableNames<DataModel_>>(
@@ -136,19 +197,21 @@ export const make = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
 
   return {
     table,
-  };
+  } as DatabaseWriterService<DatabaseSchema_>;
 };
 
 export const DatabaseWriter = <
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
->() =>
-  Context.GenericTag<ReturnType<typeof make<DatabaseSchema_>>>(
-    "@confect/server/DatabaseWriter",
-  );
+  Docs = {},
+>(): DatabaseWriterTag<DatabaseSchema_, Docs> =>
+  Context.GenericTag<
+    DatabaseWriterService<DatabaseSchema_>,
+    DatabaseWriterService<DatabaseSchema_, Docs>
+  >("@confect/server/DatabaseWriter");
 
 export type DatabaseWriter<
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
-> = ReturnType<typeof DatabaseWriter<DatabaseSchema_>>["Identifier"];
+> = DatabaseWriterService<DatabaseSchema_>;
 
 export const layer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,

package/src/Document.ts

@@ -5,10 +5,16 @@ import * as Function from "effect/Function";
 import * as ParseResult from "effect/ParseResult";
 import * as Schema from "effect/Schema";
 import type { ReadonlyRecord } from "effect/Record";
+import type * as DatabaseSchema from "./DatabaseSchema";
 import type * as DataModel from "./DataModel";
 import type { ReadonlyValue } from "./SchemaToValidator";
 import type * as TableInfo from "./TableInfo";
 
+export type Document<
+  Schema_ extends DatabaseSchema.AnyWithProps,
+  TableName extends DatabaseSchema.TableNames<Schema_>,
+> = DataModel.DocumentByName<DataModel.FromSchema<Schema_>, TableName>;
+
 export type WithoutSystemFields<Doc> = Omit<Doc, "_creationTime" | "_id">;
 
 export type Any = any;

package/src/MutationCtx.ts

@@ -1,11 +1,17 @@
 import type { GenericDataModel, GenericMutationCtx } from "convex/server";
 import * as Context from "effect/Context";
 
-export const MutationCtx = <DataModel extends GenericDataModel>() =>
+export type MutationCtxTag<DataModel extends GenericDataModel> = Context.Tag<
+  GenericMutationCtx<DataModel>,
+  GenericMutationCtx<DataModel>
+>;
+
+export const MutationCtx = <
+  DataModel extends GenericDataModel,
+>(): MutationCtxTag<DataModel> =>
   Context.GenericTag<GenericMutationCtx<DataModel>>(
     "@confect/server/MutationCtx",
   );
 
-export type MutationCtx<DataModel extends GenericDataModel> = ReturnType<
-  typeof MutationCtx<DataModel>
->["Identifier"];
+export type MutationCtx<DataModel extends GenericDataModel> =
+  GenericMutationCtx<DataModel>;

package/src/OrderedQuery.ts

@@ -15,25 +15,20 @@ import type * as TableInfo from "./TableInfo";
 export type OrderedQuery<
   TableInfo_ extends TableInfo.AnyWithProps,
   _TableName extends string,
+  Doc = TableInfo_["document"],
 > = {
   readonly first: () => Effect.Effect<
-    Option.Option<TableInfo_["document"]>,
+    Option.Option<Doc>,
     Document.DocumentDecodeError
   >;
   readonly take: (
     n: number,
-  ) => Effect.Effect<
-    ReadonlyArray<TableInfo_["document"]>,
-    Document.DocumentDecodeError
-  >;
+  ) => Effect.Effect<ReadonlyArray<Doc>, Document.DocumentDecodeError>;
   readonly collect: () => Effect.Effect<
-    ReadonlyArray<TableInfo_["document"]>,
-    Document.DocumentDecodeError
-  >;
-  readonly stream: () => Stream.Stream<
-    TableInfo_["document"],
+    ReadonlyArray<Doc>,
     Document.DocumentDecodeError
   >;
+  readonly stream: () => Stream.Stream<Doc, Document.DocumentDecodeError>;
   readonly paginate: (
     options: {
       cursor: string | null;
@@ -42,10 +37,7 @@ export type OrderedQuery<
     filter?: (
       q: FilterBuilder<TableInfo.ConvexTableInfo<TableInfo_>>,
     ) => ExpressionOrValue<boolean>,
-  ) => Effect.Effect<
-    PaginationResult<TableInfo_["document"]>,
-    Document.DocumentDecodeError
-  >;
+  ) => Effect.Effect<PaginationResult<Doc>, Document.DocumentDecodeError>;
 };
 
 export const make = <

package/src/QueryCtx.ts

@@ -1,9 +1,15 @@
 import type { GenericDataModel, GenericQueryCtx } from "convex/server";
 import * as Context from "effect/Context";
 
-export const QueryCtx = <DataModel extends GenericDataModel>() =>
+export type QueryCtxTag<DataModel extends GenericDataModel> = Context.Tag<
+  GenericQueryCtx<DataModel>,
+  GenericQueryCtx<DataModel>
+>;
+
+export const QueryCtx = <
+  DataModel extends GenericDataModel,
+>(): QueryCtxTag<DataModel> =>
   Context.GenericTag<GenericQueryCtx<DataModel>>("@confect/server/QueryCtx");
 
-export type QueryCtx<DataModel extends GenericDataModel> = ReturnType<
-  typeof QueryCtx<DataModel>
->["Identifier"];
+export type QueryCtx<DataModel extends GenericDataModel> =
+  GenericQueryCtx<DataModel>;

package/src/QueryInitializer.ts

@@ -31,57 +31,52 @@ import * as OrderedQuery from "./OrderedQuery";
 import type * as Table from "./Table";
 import type * as TableInfo from "./TableInfo";
 
-type QueryInitializer<
+export interface QueryInitializer<
   DataModel_ extends DataModel.AnyWithProps,
   TableName extends DataModel.TableNames<DataModel_>,
-  _ConvexTableInfo extends GenericTableInfo,
-  _TableInfo extends TableInfo.AnyWithProps,
-> = {
+  ConvexTableInfo_ extends GenericTableInfo,
+  TableInfo_ extends TableInfo.AnyWithProps,
+  Doc = TableInfo_["document"],
+> {
   readonly get: {
     (
       id: GenericId<TableName>,
-    ): Effect.Effect<
-      _TableInfo["document"],
-      Document.DocumentDecodeError | GetByIdFailure
-    >;
-    <IndexName extends keyof Indexes<_ConvexTableInfo>>(
+    ): Effect.Effect<Doc, Document.DocumentDecodeError | GetByIdFailure>;
+    <IndexName extends keyof Indexes<ConvexTableInfo_>>(
       indexName: IndexName,
       ...indexFieldValues: IndexFieldTypesForEq<
         DataModel.ToConvex<DataModel_>,
         TableName,
-        Indexes<_ConvexTableInfo>[IndexName]
+        Indexes<ConvexTableInfo_>[IndexName]
       >
-    ): Effect.Effect<
-      _TableInfo["document"],
-      Document.DocumentDecodeError | GetByIndexFailure
-    >;
+    ): Effect.Effect<Doc, Document.DocumentDecodeError | GetByIndexFailure>;
   };
   readonly index: {
-    <IndexName extends keyof Indexes<_ConvexTableInfo>>(
+    <IndexName extends keyof Indexes<ConvexTableInfo_>>(
       indexName: IndexName,
       indexRange?: (
         q: IndexRangeBuilder<
-          _TableInfo["convexDocument"],
-          NamedIndex<_ConvexTableInfo, IndexName>
+          TableInfo_["convexDocument"],
+          NamedIndex<ConvexTableInfo_, IndexName>
         >,
       ) => IndexRange,
       order?: "asc" | "desc",
-    ): OrderedQuery.OrderedQuery<_TableInfo, TableName>;
-    <IndexName extends keyof Indexes<_ConvexTableInfo>>(
+    ): OrderedQuery.OrderedQuery<TableInfo_, TableName, Doc>;
+    <IndexName extends keyof Indexes<ConvexTableInfo_>>(
       indexName: IndexName,
       order?: "asc" | "desc",
-    ): OrderedQuery.OrderedQuery<_TableInfo, TableName>;
+    ): OrderedQuery.OrderedQuery<TableInfo_, TableName, Doc>;
   };
-  readonly search: <IndexName extends keyof SearchIndexes<_ConvexTableInfo>>(
+  readonly search: <IndexName extends keyof SearchIndexes<ConvexTableInfo_>>(
     indexName: IndexName,
     searchFilter: (
       q: SearchFilterBuilder<
-        DocumentByInfo<_ConvexTableInfo>,
-        NamedSearchIndex<_ConvexTableInfo, IndexName>
+        DocumentByInfo<ConvexTableInfo_>,
+        NamedSearchIndex<ConvexTableInfo_, IndexName>
       >,
     ) => SearchFilter,
-  ) => OrderedQuery.OrderedQuery<_TableInfo, TableName>;
-};
+  ) => OrderedQuery.OrderedQuery<TableInfo_, TableName, Doc>;
+}
 
 export const make = <
   Tables extends Table.AnyWithProps,
@@ -148,7 +143,7 @@ export const make = <
             new GetByIndexFailure({
               tableName,
               indexName: indexName as string,
-              indexFieldValues: indexFieldValues as string[],
+              indexFieldValues,
             }),
         ),
       ),
@@ -313,10 +308,13 @@ export class GetByIndexFailure extends Schema.TaggedError<GetByIndexFailure>()(
   {
     tableName: Schema.String,
     indexName: Schema.String,
-    indexFieldValues: Schema.Array(Schema.String),
+    indexFieldValues: Schema.Array(Schema.Unknown),
   },
 ) {
   override get message(): string {
-    return `No documents found in table '${this.tableName}' with index '${this.indexName}' and field values '${this.indexFieldValues}'`;
+    return `No documents found in table '${this.tableName}' with index '${this.indexName}' and field values '${JSON.stringify(
+      this.indexFieldValues,
+      (_key, value) => (typeof value === "bigint" ? value.toString() : value),
+    )}'`;
   }
 }

package/src/VectorSearch.ts

@@ -14,10 +14,13 @@ import type * as DataModel from "./DataModel";
 type ConvexVectorSearch<DataModel_ extends DataModel.AnyWithProps> =
   GenericActionCtx<DataModel.ToConvex<DataModel_>>["vectorSearch"];
 
-export const make =
-  <DataModel_ extends DataModel.AnyWithProps>(
-    vectorSearch: ConvexVectorSearch<DataModel_>,
-  ) =>
+/**
+ * The service shape backing the `VectorSearch` tag. Named so declaration emit
+ * references it instead of expanding the call signature at every usage.
+ */
+export interface VectorSearchService<
+  DataModel_ extends DataModel.AnyWithProps,
+> {
   <
     TableName extends DataModel.TableNames<DataModel_>,
     IndexName extends VectorIndexNames<
@@ -32,16 +35,28 @@ export const make =
         IndexName
       >
     >,
-  ): Effect.Effect<Array<{ _id: GenericId<TableName>; _score: number }>> =>
+  ): Effect.Effect<Array<{ _id: GenericId<TableName>; _score: number }>>;
+}
+
+export type VectorSearchTag<DataModel_ extends DataModel.AnyWithProps> =
+  Context.Tag<VectorSearchService<DataModel_>, VectorSearchService<DataModel_>>;
+
+export const make =
+  <DataModel_ extends DataModel.AnyWithProps>(
+    vectorSearch: ConvexVectorSearch<DataModel_>,
+  ): VectorSearchService<DataModel_> =>
+  (tableName, indexName, query) =>
     Effect.promise(() => vectorSearch(tableName, indexName, query));
 
-export const VectorSearch = <DataModel_ extends DataModel.AnyWithProps>() =>
-  Context.GenericTag<ReturnType<typeof make<DataModel_>>>(
+export const VectorSearch = <
+  DataModel_ extends DataModel.AnyWithProps,
+>(): VectorSearchTag<DataModel_> =>
+  Context.GenericTag<VectorSearchService<DataModel_>>(
     "@confect/server/VectorSearch",
   );
 
 export type VectorSearch<DataModel_ extends DataModel.AnyWithProps> =
-  ReturnType<typeof VectorSearch<DataModel_>>["Identifier"];
+  VectorSearchService<DataModel_>;
 
 export const layer = <DataModel_ extends DataModel.AnyWithProps>(
   vectorSearch: ConvexVectorSearch<DataModel_>,