@gaganref/confect-server 0.0.0-stage → 10.3.1-fork.2

package/src/DatabaseReader.ts

@@ -0,0 +1,118 @@
+import type { GenericDatabaseReader } from "convex/server";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import type { BaseDatabaseReader } from "@confect/core/Types";
+import * as DatabaseSchema from "./DatabaseSchema";
+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<DatabaseSchema.Scope<DatabaseSchema_>>;
+
+type IncludedDataModel<DatabaseSchema_ extends DatabaseSchema.AnyWithProps> =
+  DataModel.FromTables<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,
+    TableName extends keyof Docs
+      ? Docs[TableName]
+      : DataModel.DocumentWithName<
+          IncludedDataModel<DatabaseSchema_>,
+          TableName
+        >,
+    DatabaseSchema_["target"]["kind"]
+  >;
+}
+
+export const make = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
+  databaseSchema: DatabaseSchema_,
+  convexDatabaseReader: GenericDatabaseReader<
+    DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+  >,
+): DatabaseReaderService<DatabaseSchema_> => {
+  const systemTables = Table.systemTablesForScope(databaseSchema.target.scope);
+  return {
+    table: <
+      const TableName extends Table.Name<IncludedTables<DatabaseSchema_>>,
+    >(
+      tableName: TableName,
+    ) => {
+      const isSystem = Object.hasOwn(systemTables, tableName);
+
+      const baseDatabaseReader: BaseDatabaseReader<any> = isSystem
+        ? {
+            get: convexDatabaseReader.system.get.bind(
+              convexDatabaseReader.system,
+            ),
+            query: convexDatabaseReader.system.query.bind(
+              convexDatabaseReader.system,
+            ),
+          }
+        : {
+            get: convexDatabaseReader.get.bind(convexDatabaseReader),
+            query: convexDatabaseReader.query.bind(convexDatabaseReader),
+          };
+
+      const table = (
+        isSystem
+          ? (systemTables as Record<string, Table.AnyWithProps>)[tableName]
+          : DatabaseSchema.tables(databaseSchema)[tableName]
+      ) as Table.WithName<IncludedTables<DatabaseSchema_>, TableName>;
+
+      return QueryInitializer.make<IncludedTables<DatabaseSchema_>, 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.Service<
+  DatabaseReaderService<DatabaseSchema_>,
+  DatabaseReaderService<DatabaseSchema_, Docs>
+>;
+
+export const DatabaseReader = <
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+>(): DatabaseReaderTag<DatabaseSchema_, Docs> =>
+  Context.Service<
+    DatabaseReaderService<DatabaseSchema_>,
+    DatabaseReaderService<DatabaseSchema_, Docs>
+  >("@confect/server/DatabaseReader");
+
+export type DatabaseReader<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+> = DatabaseReaderService<DatabaseSchema_>;
+
+export const layer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
+  databaseSchema: DatabaseSchema_,
+  convexDatabaseReader: GenericDatabaseReader<
+    DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+  >,
+) =>
+  Layer.succeed(
+    DatabaseReader<DatabaseSchema_>(),
+    make(databaseSchema, convexDatabaseReader),
+  );

package/src/DatabaseSchema.ts

@@ -0,0 +1,139 @@
+import * as IdScope from "@confect/core/IdScope";
+import * as Data from "effect/Data";
+import * as Result from "effect/Result";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import type * as Table from "./Table";
+
+export class EmptyDatabaseScopeError extends Data.TaggedError(
+  "EmptyDatabaseScopeError",
+)<{
+  readonly databaseScope: IdScope.IdScope;
+}> {
+  override get message(): string {
+    return "A component database schema requires a nonempty ID scope.";
+  }
+}
+
+export class TableBindingMismatchError extends Data.TaggedError(
+  "TableBindingMismatchError",
+)<{
+  readonly bindingName: string;
+  readonly tableName: string;
+  readonly tableScope: IdScope.IdScope;
+  readonly databaseScope: IdScope.IdScope;
+}> {
+  override get message(): string {
+    return `Table '${this.bindingName}' must be bound to its database schema's name and ID scope.`;
+  }
+}
+
+export const TypeId = "~@confect/server/DatabaseSchema";
+export type TypeId = typeof TypeId;
+
+export interface AppTarget {
+  readonly kind: "app";
+  readonly scope: IdScope.App;
+}
+
+export interface ComponentTarget<
+  Scope_ extends IdScope.IdScope = IdScope.IdScope,
+> {
+  readonly kind: "component";
+  readonly scope: Scope_;
+}
+
+export type Target = AppTarget | ComponentTarget;
+
+export interface Any {
+  readonly [TypeId]: unknown;
+}
+
+export const isDatabaseSchema = (u: unknown): u is Any =>
+  Predicate.hasProperty(u, TypeId);
+
+/**
+ * A schema definition holding a record of bound `Table`s keyed by table name.
+ * Codegen emits a single static `DatabaseSchema.make({ ... })` call; laziness
+ * lives entirely on each `Table` (its `Fields` and `Doc` are lazy memoised
+ * getters), so this layer is a plain record indirection with no module-loading
+ * or async machinery.
+ */
+export interface DatabaseSchema<
+  Tables_ extends Readonly<Record<string, Table.AnyWithProps>> = {},
+  Target_ extends Target = AppTarget,
+> {
+  readonly [TypeId]: Readonly<Tables_>;
+  readonly target: Target_;
+}
+
+export interface AnyWithProps extends DatabaseSchema<
+  Readonly<Record<string, Table.AnyWithProps>>,
+  Target
+> {}
+
+export type Scope<Schema extends AnyWithProps> = Schema["target"]["scope"];
+
+export type Tables<DatabaseSchema_ extends AnyWithProps> =
+  DatabaseSchema_[TypeId][keyof DatabaseSchema_[TypeId]];
+
+/**
+ * The bound table record, without evaluating any table schemas.
+ */
+export const tables = <Schema extends AnyWithProps>(
+  self: Schema,
+): Schema[TypeId] => self[TypeId];
+
+export type TableNames<DatabaseSchema_ extends AnyWithProps> = Table.Name<
+  Tables<DatabaseSchema_>
+> &
+  string;
+
+export type TableWithName<
+  DatabaseSchema_ extends AnyWithProps,
+  TableName extends TableNames<DatabaseSchema_>,
+> = Extract<Tables<DatabaseSchema_>, { readonly tableName: TableName }>;
+
+const validateBindings = (
+  tableRecord: Readonly<Record<string, Table.AnyWithProps>>,
+  target: Target,
+): Result.Result<void, EmptyDatabaseScopeError | TableBindingMismatchError> => {
+  if (target.kind === "component" && target.scope === "") {
+    return Result.fail(
+      new EmptyDatabaseScopeError({ databaseScope: target.scope }),
+    );
+  }
+  for (const [name, table] of Record.toEntries(tableRecord)) {
+    if (name !== table.tableName || table.scope !== target.scope) {
+      return Result.fail(
+        new TableBindingMismatchError({
+          bindingName: name,
+          tableName: table.tableName,
+          tableScope: table.scope,
+          databaseScope: target.scope,
+        }),
+      );
+    }
+  }
+  return Result.succeed(undefined);
+};
+
+/**
+ * Construct a database schema from its bound table record. The record's keys
+ * must match their tables' names. Table schemas remain lazy; construction only
+ * stores the record. The empty case is `make({})`.
+ */
+export const make = <
+  const TablesRecord extends Readonly<Record<string, Table.AnyWithProps>>,
+  const Target_ extends Target = AppTarget,
+>(
+  tableRecord: TablesRecord,
+  target?: Target_,
+): DatabaseSchema<TablesRecord, Target_> => {
+  const resolvedTarget = target ?? { kind: "app", scope: IdScope.app };
+  Result.getOrThrow(validateBindings(tableRecord, resolvedTarget));
+  return {
+    [TypeId]: tableRecord,
+    target: resolvedTarget,
+  } as DatabaseSchema<TablesRecord, Target_>;
+};

package/src/DatabaseWriter.ts

@@ -0,0 +1,232 @@
+import type {
+  BetterOmit,
+  DocumentByName,
+  Expand,
+  GenericDatabaseWriter,
+  WithoutSystemFields,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import { pipe } from "effect/Function";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Record from "effect/Record";
+import * as DatabaseSchema from "./DatabaseSchema";
+import type * as DataModel from "./DataModel";
+import type { DocumentByName as DocumentByName_ } from "./DataModel";
+import * as Document from "./Document";
+import * as QueryInitializer from "./QueryInitializer";
+import type * as Table from "./Table";
+
+/**
+ * The argument accepted by `patch`: like `Partial<Doc>` without system fields,
+ * but the fields that are already optional also accept `undefined`, since
+ * setting a field to `undefined` unsets it.
+ */
+export type PatchValue<Doc> = {
+  [
+    K in keyof Doc as K extends "_id" | "_creationTime" ? never : K
+  ]?: undefined extends Doc[K] ? Doc[K] | undefined : Doc[K];
+};
+
+export interface DatabaseWriterTableAccessor<
+  DataModel_ extends DataModel.AnyWithProps,
+  TableName extends DataModel.TableNames<DataModel_>,
+  Doc = DocumentByName_<DataModel_, TableName>,
+> {
+  readonly insert: (
+    document: Document.WithoutSystemFields<Doc>,
+  ) => Effect.Effect<
+    DataModel.Id<DataModel_, TableName>,
+    Document.DocumentEncodeError
+  >;
+  readonly patch: (
+    id: DataModel.Id<DataModel_, TableName>,
+    patchedValues: PatchValue<Doc>,
+  ) => Effect.Effect<
+    void,
+    | QueryInitializer.GetByIdFailure
+    | Document.DocumentDecodeError
+    | Document.DocumentEncodeError
+  >;
+  readonly replace: (
+    id: DataModel.Id<DataModel_, TableName>,
+    value: Document.WithoutSystemFields<Doc>,
+  ) => Effect.Effect<void, Document.DocumentEncodeError>;
+  readonly delete: (
+    id: DataModel.Id<DataModel_, 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.Service<
+  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_>>(
+    tableName: TableName,
+  ) => {
+    const tableDef = DatabaseSchema.tables(databaseSchema)[tableName];
+
+    const insert = Effect.fn("DatabaseWriter.insert")(function* (
+      document: Document.WithoutSystemFields<
+        DocumentByName_<DataModel_, TableName>
+      >,
+    ) {
+      const encodedDocument = yield* Document.encode(document, tableDef);
+
+      const id = yield* Effect.promise(() =>
+        convexDatabaseWriter.insert(
+          tableName,
+          encodedDocument as WithoutSystemFields<
+            DocumentByName<DataModel.ToConvex<DataModel_>, TableName>
+          >,
+        ),
+      );
+
+      // The database supplies the ID in this table's execution scope. Its
+      // scope brand is erased at the Convex syscall boundary.
+      return id as unknown as DataModel.Id<DataModel_, TableName>;
+    });
+
+    const patch = Effect.fn("DatabaseWriter.patch")(function* (
+      id: DataModel.Id<DataModel_, TableName>,
+      patchedValues: PatchValue<
+        Document.WithoutSystemFields<DocumentByName_<DataModel_, TableName>>
+      >,
+    ) {
+      const originalDecodedDoc = yield* QueryInitializer.getById<
+        Table.AnyWithProps,
+        TableName
+      >(
+        convexDatabaseWriter as any,
+        tableDef,
+      )(id as unknown as GenericId<TableName>);
+
+      const updatedEncodedDoc = yield* pipe(
+        patchedValues,
+        Record.reduce(originalDecodedDoc, (acc, value, key) =>
+          value === undefined
+            ? Record.remove(acc, key)
+            : Record.set(acc, key, value),
+        ),
+        Document.encode(tableDef),
+      );
+
+      yield* Effect.promise(() =>
+        convexDatabaseWriter.replace(
+          id as unknown as GenericId<TableName>,
+          updatedEncodedDoc as Expand<
+            BetterOmit<
+              DocumentByName<DataModel.ToConvex<DataModel_>, TableName>,
+              "_creationTime" | "_id"
+            >
+          >,
+        ),
+      );
+    });
+
+    const replace = Effect.fn("DatabaseWriter.replace")(function* (
+      id: DataModel.Id<DataModel_, TableName>,
+      value: Document.WithoutSystemFields<
+        DocumentByName_<DataModel_, TableName>
+      >,
+    ) {
+      const updatedEncodedDoc = yield* Document.encode(value, tableDef);
+
+      yield* Effect.promise(() =>
+        convexDatabaseWriter.replace(
+          id as unknown as GenericId<TableName>,
+          updatedEncodedDoc as Expand<
+            BetterOmit<
+              DocumentByName<DataModel.ToConvex<DataModel_>, TableName>,
+              "_creationTime" | "_id"
+            >
+          >,
+        ),
+      );
+    });
+
+    const delete_ = (id: DataModel.Id<DataModel_, TableName>) =>
+      Effect.promise(() =>
+        convexDatabaseWriter.delete(id as unknown as GenericId<TableName>),
+      );
+
+    return {
+      insert,
+      patch,
+      replace,
+      delete: delete_,
+    };
+  };
+
+  return {
+    table,
+  } as DatabaseWriterService<DatabaseSchema_>;
+};
+
+export const DatabaseWriter = <
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Docs = {},
+>(): DatabaseWriterTag<DatabaseSchema_, Docs> =>
+  Context.Service<
+    DatabaseWriterService<DatabaseSchema_>,
+    DatabaseWriterService<DatabaseSchema_, Docs>
+  >("@confect/server/DatabaseWriter");
+
+export type DatabaseWriter<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+> = DatabaseWriterService<DatabaseSchema_>;
+
+export const layer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
+  databaseSchema: DatabaseSchema_,
+  convexDatabaseWriter: GenericDatabaseWriter<
+    DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+  >,
+) =>
+  Layer.succeed(
+    DatabaseWriter<DatabaseSchema_>(),
+    make(databaseSchema, convexDatabaseWriter),
+  );

package/src/Document.ts

@@ -0,0 +1,146 @@
+import type { ReadonlyValue } from "@confect/core/SchemaToValidator";
+import { pipe } from "effect/Function";
+import * as Effect from "effect/Effect";
+import * as Function from "effect/Function";
+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 * as TableInfo from "./TableInfo";
+import type * as Table from "./Table";
+
+export type Document<
+  Schema_ extends DatabaseSchema.AnyWithProps,
+  TableName extends DatabaseSchema.TableNames<Schema_>,
+> = DataModel.DocumentByName<DataModel.FromSchema<Schema_>, TableName>;
+
+export type WithoutSystemFields<Doc> = Doc extends unknown
+  ? Omit<Doc, "_creationTime" | "_id">
+  : never;
+
+export type Any = any;
+export type AnyEncoded = ReadonlyRecord<string, ReadonlyValue>;
+
+export const decode = Function.dual<
+  <Table_ extends Table.AnyWithProps>(
+    table: Table_,
+  ) => (
+    self: TableInfo.TableInfo<Table_>["convexDocument"],
+  ) => Effect.Effect<
+    TableInfo.TableInfo<Table_>["document"],
+    DocumentDecodeError
+  >,
+  <Table_ extends Table.AnyWithProps>(
+    self: TableInfo.TableInfo<Table_>["convexDocument"],
+    table: Table_,
+  ) => Effect.Effect<
+    TableInfo.TableInfo<Table_>["document"],
+    DocumentDecodeError
+  >
+>(
+  2,
+  <Table_ extends Table.AnyWithProps>(
+    self: TableInfo.TableInfo<Table_>["convexDocument"],
+    table: Table_,
+  ): Effect.Effect<
+    TableInfo.TableInfo<Table_>["document"],
+    DocumentDecodeError
+  > =>
+    pipe(
+      self,
+      Schema.decodeUnknownEffect(table.Doc),
+      Effect.catchIf(Schema.isSchemaError, (schemaError) =>
+        Effect.fail(
+          new DocumentDecodeError({
+            tableName: table.tableName,
+            id: self._id,
+            parseError: schemaError.message,
+          }),
+        ),
+      ),
+    ),
+);
+
+export const encode = Function.dual<
+  <Table_ extends Table.AnyWithProps>(
+    table: Table_,
+  ) => (
+    self: Schema.Schema.Type<Table.Fields<Table_>>,
+  ) => Effect.Effect<
+    Schema.Codec.Encoded<Table.Fields<Table_>>,
+    DocumentEncodeError
+  >,
+  <Table_ extends Table.AnyWithProps>(
+    self: Schema.Schema.Type<Table.Fields<Table_>>,
+    table: Table_,
+  ) => Effect.Effect<
+    Schema.Codec.Encoded<Table.Fields<Table_>>,
+    DocumentEncodeError
+  >
+>(
+  2,
+  <Table_ extends Table.AnyWithProps>(
+    self: Schema.Schema.Type<Table.Fields<Table_>>,
+    table: Table_,
+  ): Effect.Effect<
+    Schema.Codec.Encoded<Table.Fields<Table_>>,
+    DocumentEncodeError
+  > =>
+    pipe(
+      self,
+      Schema.encodeEffect(table.Fields),
+      Effect.catchIf(Schema.isSchemaError, (schemaError) =>
+        Effect.fail(
+          new DocumentEncodeError({
+            tableName: table.tableName,
+            id: self._id,
+            parseError: schemaError.message,
+          }),
+        ),
+      ),
+    ),
+);
+
+export class DocumentDecodeError extends Schema.TaggedError<DocumentDecodeError>()(
+  "DocumentDecodeError",
+  {
+    tableName: Schema.String,
+    id: Schema.String,
+    parseError: Schema.String,
+  },
+) {
+  override get message(): string {
+    return documentErrorMessage({
+      id: this.id,
+      tableName: this.tableName,
+      message: `could not be decoded:\n\n${this.parseError}`,
+    });
+  }
+}
+
+export class DocumentEncodeError extends Schema.TaggedError<DocumentEncodeError>()(
+  "DocumentEncodeError",
+  {
+    tableName: Schema.String,
+    id: Schema.String,
+    parseError: Schema.String,
+  },
+) {
+  override get message(): string {
+    return documentErrorMessage({
+      id: this.id,
+      tableName: this.tableName,
+      message: `could not be encoded:\n\n${this.parseError}`,
+    });
+  }
+}
+
+export const documentErrorMessage = ({
+  id,
+  tableName,
+  message,
+}: {
+  id: string;
+  tableName: string;
+  message: string;
+}) => `Document with ID '${id}' in table '${tableName}' ${message}`;

package/src/ExecutionMetadata.ts

@@ -0,0 +1,26 @@
+import type { QueryMeta } from "convex/server";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+export type { DeploymentMetadata, FunctionMetadata } from "convex/server";
+
+const make = (
+  meta: Pick<QueryMeta, "getFunctionMetadata" | "getDeploymentMetadata">,
+) => ({
+  getFunction: Effect.fn("ExecutionMetadata.getFunction")(() =>
+    Effect.promise(() => meta.getFunctionMetadata()),
+  ),
+  getDeployment: Effect.fn("ExecutionMetadata.getDeployment")(() =>
+    Effect.promise(() => meta.getDeploymentMetadata()),
+  ),
+});
+
+export class ExecutionMetadata extends Context.Service<
+  ExecutionMetadata,
+  ReturnType<typeof make>
+>()("@confect/server/ExecutionMetadata") {}
+
+export const layer = (
+  meta: Pick<QueryMeta, "getFunctionMetadata" | "getDeploymentMetadata">,
+) => Layer.succeed(ExecutionMetadata, make(meta));