@gaganref/confect-core 10.3.1-fork.8 → 10.3.1-fork.81

package/src/Table.ts

@@ -1,3 +1,4 @@
+import * as GenericId from "./GenericId.js";
 import * as IdScope from "./IdScope.js";
 import * as Lazy from "./Lazy.js";
 import * as SystemFields from "./SystemFields.js";
@@ -12,7 +13,13 @@ import type {
   SearchIndexConfig,
   VectorIndexConfig,
 } from "convex/server";
-import type { GenericValidator, Validator } from "convex/values";
+import type {
+  GenericId as ConvexGenericId,
+  GenericValidator,
+  Validator,
+} from "convex/values";
+import * as Data from "effect/Data";
+import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import type * as Schema from "effect/Schema";
 
@@ -36,6 +43,97 @@ export const isTable = (u: unknown): u is Any =>
 export const isUnnamedTable = (u: unknown): u is UnnamedAny =>
   Predicate.hasProperty(u, TypeId) && !Predicate.hasProperty(u, "tableName");
 
+// -----------------------------------------------------------------------------
+// Group
+// -----------------------------------------------------------------------------
+//
+// A table is grouped by one of its required id fields, and the id's table owns
+// its rows. `table` and `scope` come from the id's schema on first read, so
+// binding a table never builds its `Fields`.
+
+export interface Group<
+  Key extends string = string,
+  Table_ extends string = string,
+  Scope_ extends IdScope.IdScope = IdScope.IdScope,
+> {
+  readonly key: Key;
+  readonly table: Table_;
+  readonly scope: Scope_;
+}
+
+export class GroupFieldError extends Data.TaggedError("GroupFieldError")<{
+  readonly tableName: string;
+  readonly key: string;
+}> {
+  override get message(): string {
+    return `Table '${this.tableName}' cannot be grouped by '${this.key}': it is not a field holding an id.`;
+  }
+}
+
+type FieldsOf<TableSchema_> = TableSchema_ extends {
+  readonly fields: infer StructFields extends Schema.Struct.Fields;
+}
+  ? StructFields
+  : never;
+
+type GroupKeys<TableSchema_> = {
+  [
+    Key in keyof FieldsOf<TableSchema_> & string
+  ]: FieldsOf<TableSchema_>[Key] extends {
+    readonly Type: ConvexGenericId<string>;
+  }
+    ? [FieldsOf<TableSchema_>[Key]["~type.optionality"]] extends ["optional"]
+      ? never
+      : Key
+    : never;
+}[keyof FieldsOf<TableSchema_> & string];
+
+type IdTableName<Id> = Id extends {
+  readonly "~@confect/core/ScopedId": {
+    readonly table: infer TableName extends string;
+  };
+}
+  ? TableName
+  : Id extends ConvexGenericId<infer TableName>
+    ? TableName
+    : never;
+
+type IdScopeOf<Id> = Id extends {
+  readonly "~@confect/core/ScopedId": {
+    readonly scope: infer Scope_ extends IdScope.IdScope;
+  };
+}
+  ? Scope_
+  : IdScope.App;
+
+type GroupOf<TableSchema_, Key extends string> = Group<
+  Key,
+  IdTableName<
+    FieldsOf<TableSchema_>[Key & keyof FieldsOf<TableSchema_>]["Type"]
+  >,
+  IdScopeOf<FieldsOf<TableSchema_>[Key & keyof FieldsOf<TableSchema_>]["Type"]>
+>;
+
+const makeGroup = (
+  tableName: string,
+  key: string,
+  fields: () => Schema.Codec<any, any>,
+): Group => {
+  const idField = () => {
+    const ast = (fields() as { readonly fields?: Schema.Struct.Fields })
+      .fields?.[key]?.ast;
+    const table =
+      ast === undefined ? Option.none() : GenericId.tableName<string>(ast);
+    if (ast === undefined || Option.isNone(table))
+      throw new GroupFieldError({ tableName, key });
+    return { table: table.value, scope: GenericId.scope(ast) };
+  };
+  const group = { key };
+  Lazy.defineProperty(group, "table", () => idField().table);
+  Lazy.defineProperty(group, "scope", () => idField().scope);
+  return group as Group;
+};
+
 // -----------------------------------------------------------------------------
 // Bound Table
 // -----------------------------------------------------------------------------
@@ -54,10 +152,12 @@ export interface Table<
   SearchIndexes_ extends GenericTableSearchIndexes = {},
   VectorIndexes_ extends GenericTableVectorIndexes = {},
   Scope_ extends IdScope.IdScope = IdScope.App,
+  Group_ extends Group | undefined = undefined,
 > {
   readonly [TypeId]: TypeId;
   readonly tableName: Name_;
   readonly scope: Scope_;
+  readonly group: Group_;
   readonly Fields: TableSchema_;
   readonly Doc: SystemFields.ExtendWithSystemFields<
     Name_,
@@ -82,7 +182,8 @@ export type AnyWithProps = Table<
   GenericTableIndexes,
   GenericTableSearchIndexes,
   GenericTableVectorIndexes,
-  IdScope.IdScope
+  IdScope.IdScope,
+  Group | undefined
 >;
 
 // -----------------------------------------------------------------------------
@@ -105,6 +206,7 @@ export interface UnnamedTable<
   Indexes_ extends GenericTableIndexes = {},
   SearchIndexes_ extends GenericTableSearchIndexes = {},
   VectorIndexes_ extends GenericTableVectorIndexes = {},
+  Group_ extends Group | undefined = undefined,
 > {
   <
     const Name_ extends string,
@@ -119,7 +221,8 @@ export interface UnnamedTable<
     Indexes_,
     SearchIndexes_,
     VectorIndexes_,
-    Scope_
+    Scope_,
+    Group_
   >;
 
   readonly [TypeId]: TypeId;
@@ -146,7 +249,8 @@ export interface UnnamedTable<
         >
     >,
     SearchIndexes_,
-    VectorIndexes_
+    VectorIndexes_,
+    Group_
   >;
 
   searchIndex<
@@ -170,7 +274,8 @@ export interface UnnamedTable<
           }
         >
     >,
-    VectorIndexes_
+    VectorIndexes_,
+    Group_
   >;
 
   vectorIndex<
@@ -195,7 +300,23 @@ export interface UnnamedTable<
             filterFields: FilterFields;
           }
         >
-    >
+    >,
+    Group_
+  >;
+
+  /**
+   * Name the required id field that groups this table's rows. The field's table
+   * is the one whose rows own these rows.
+   */
+  group<const Key extends GroupKeys<TableSchema_>>(
+    key: Key,
+  ): UnnamedTable<
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    VectorIndexes_,
+    GroupOf<TableSchema_, Key>
   >;
 }
 
@@ -208,7 +329,8 @@ export type UnnamedAnyWithProps = UnnamedTable<
   GenericValidator,
   GenericTableIndexes,
   GenericTableSearchIndexes,
-  GenericTableVectorIndexes
+  GenericTableVectorIndexes,
+  Group | undefined
 >;
 
 // -----------------------------------------------------------------------------
@@ -266,6 +388,7 @@ interface UnnamedState<
   VectorIndexes_ extends GenericTableVectorIndexes,
 > {
   readonly lazyFields: () => TableSchema_;
+  readonly groupKey: string | undefined;
   readonly indexes: Indexes_;
   readonly searchIndexes: SearchIndexes_;
   readonly vectorIndexes: VectorIndexes_;
@@ -279,6 +402,7 @@ const makeBound = <
   SearchIndexes_ extends GenericTableSearchIndexes,
   VectorIndexes_ extends GenericTableVectorIndexes,
   Scope_ extends IdScope.IdScope,
+  Group_ extends Group | undefined,
 >(
   tableName: Name_,
   state: UnnamedState<TableSchema_, Indexes_, SearchIndexes_, VectorIndexes_>,
@@ -290,12 +414,17 @@ const makeBound = <
   Indexes_,
   SearchIndexes_,
   VectorIndexes_,
-  Scope_
+  Scope_,
+  Group_
 > => {
   const bound = {
     [TypeId]: TypeId as TypeId,
     tableName,
     scope,
+    group:
+      state.groupKey === undefined
+        ? undefined
+        : makeGroup(tableName, state.groupKey, () => bound.Fields),
     indexes: state.indexes,
     searchIndexes: state.searchIndexes,
     vectorIndexes: state.vectorIndexes,
@@ -306,7 +435,8 @@ const makeBound = <
     Indexes_,
     SearchIndexes_,
     VectorIndexes_,
-    Scope_
+    Scope_,
+    Group_
   >;
 
   Lazy.defineProperty(bound, "Fields", () => state.lazyFields());
@@ -328,6 +458,7 @@ const makeUnnamed = <
   Indexes_ extends GenericTableIndexes,
   SearchIndexes_ extends GenericTableSearchIndexes,
   VectorIndexes_ extends GenericTableVectorIndexes,
+  Group_ extends Group | undefined,
 >(
   state: UnnamedState<TableSchema_, Indexes_, SearchIndexes_, VectorIndexes_>,
 ): UnnamedTable<
@@ -335,14 +466,16 @@ const makeUnnamed = <
   TableValidator_,
   Indexes_,
   SearchIndexes_,
-  VectorIndexes_
+  VectorIndexes_,
+  Group_
 > => {
   type UnnamedTable_ = UnnamedTable<
     TableSchema_,
     TableValidator_,
     Indexes_,
     SearchIndexes_,
-    VectorIndexes_
+    VectorIndexes_,
+    Group_
   >;
 
   type UnnamedTableFunction<FunctionName extends keyof UnnamedTable_> =
@@ -361,7 +494,8 @@ const makeUnnamed = <
     Indexes_,
     SearchIndexes_,
     VectorIndexes_,
-    Scope_
+    Scope_,
+    Group_
   > =>
     makeBound<
       Name_,
@@ -370,18 +504,17 @@ const makeUnnamed = <
       Indexes_,
       SearchIndexes_,
       VectorIndexes_,
-      Scope_
+      Scope_,
+      Group_
     >(tableName, state, (scope ?? IdScope.app) as Scope_);
 
   const index: UnnamedTableFunction<"index"> = (name, fields) =>
     makeUnnamed({
-      lazyFields: state.lazyFields,
+      ...state,
       indexes: {
         ...state.indexes,
         [name]: fields,
       } as any,
-      searchIndexes: state.searchIndexes,
-      vectorIndexes: state.vectorIndexes,
     });
 
   const searchIndex: UnnamedTableFunction<"searchIndex"> = (
@@ -389,13 +522,11 @@ const makeUnnamed = <
     indexConfig,
   ) =>
     makeUnnamed({
-      lazyFields: state.lazyFields,
-      indexes: state.indexes,
+      ...state,
       searchIndexes: {
         ...state.searchIndexes,
         [name]: indexConfig,
       } as any,
-      vectorIndexes: state.vectorIndexes,
     });
 
   const vectorIndex: UnnamedTableFunction<"vectorIndex"> = (
@@ -403,15 +534,16 @@ const makeUnnamed = <
     indexConfig,
   ) =>
     makeUnnamed({
-      lazyFields: state.lazyFields,
-      indexes: state.indexes,
-      searchIndexes: state.searchIndexes,
+      ...state,
       vectorIndexes: {
         ...state.vectorIndexes,
         [name]: indexConfig,
       } as any,
     });
 
+  const group: UnnamedTableFunction<"group"> = (key) =>
+    makeUnnamed({ ...state, groupKey: key });
+
   return Object.assign(bind, {
     [TypeId]: TypeId as TypeId,
     indexes: state.indexes,
@@ -420,6 +552,7 @@ const makeUnnamed = <
     index,
     searchIndex,
     vectorIndex,
+    group,
   }) as UnnamedTable_;
 };
 
@@ -429,8 +562,9 @@ export const make = <const TableSchema_ extends Schema.Codec<any, any>>(
   type TableValidator_ = TableSchemaToTableValidator<TableSchema_>;
   type UnnamedTable_ = UnnamedTable<TableSchema_, TableValidator_>;
 
-  return makeUnnamed<TableSchema_, TableValidator_, {}, {}, {}>({
+  return makeUnnamed<TableSchema_, TableValidator_, {}, {}, {}, undefined>({
     lazyFields,
+    groupKey: undefined,
     indexes: {},
     searchIndexes: {},
     vectorIndexes: {},

package/src/index.ts

@@ -1,3 +1,4 @@
+export * as ActionCall from "./ActionCall.js";
 export * as Callback from "./Callback.js";
 export * as FunctionProvenance from "./FunctionProvenance.js";
 export * as FunctionSpec from "./FunctionSpec.js";
@@ -13,11 +14,14 @@ export * as GroupSpec from "./GroupSpec.js";
 export * as Identifier from "./Identifier.js";
 export * as Lazy from "./Lazy.js";
 export * as Manifest from "./Manifest.js";
+export * as ManifestSection from "./ManifestSection.js";
+export * as Mount from "./Mount.js";
 export * as MiddlewareAttachment from "./MiddlewareAttachment.js";
 export * as MiddlewareSpec from "./MiddlewareSpec.js";
 export * as PaginationError from "./PaginationError.js";
 export * as PaginationOptions from "./PaginationOptions.js";
 export * as PaginationResult from "./PaginationResult.js";
+export * as Profile from "./Profile.js";
 export * as Ref from "./Ref.js";
 export * as Refs from "./Refs.js";
 export * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";

package/src/internal/annotations.ts

@@ -0,0 +1 @@
+export const CallbackContract = "~@confect/core/Callback/Contract";

package/src/internal/scalarDocs.ts

@@ -0,0 +1,72 @@
+import * as Effect from "effect/Effect";
+import * as HttpRouter from "effect/http/HttpRouter";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import type * as HttpApi from "effect/http-api/HttpApi";
+import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
+import * as OpenApi from "effect/http-api/OpenApi";
+
+const escape = (value: string) =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const escapeAttribute = (value: string) =>
+  escape(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+
+const escapeJson = (value: unknown) =>
+  JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+
+// WORKAROUND: Effect 4.0.6's HttpApiScalar module imports its inline Scalar
+// script dynamically, and Convex's bundler then splits a schema that reaches it
+// into an imported chunk, which Convex refuses. This copies `layerCdn`'s page
+// byte for byte. Remove when `checkSchemaBundle.mjs` passes with
+// `HttpApiScalar.layerCdn` restored.
+export const scalarDocs = <
+  Id extends string,
+  Groups extends HttpApiGroup.Constraint,
+>(
+  api: HttpApi.HttpApi<Id, Groups>,
+  path: `/${string}`,
+) =>
+  HttpRouter.use((router) => {
+    let response: HttpServerResponse.HttpServerResponse | undefined;
+    return router.add(
+      "GET",
+      path,
+      Effect.sync(() => {
+        if (response !== undefined) return response;
+        const spec = OpenApi.fromApi(api);
+        const description = (tag: string) =>
+          !spec.info.description
+            ? ""
+            : `<meta name="${tag}" content="${escapeAttribute(spec.info.description)}"/>`;
+        response = HttpServerResponse.html(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>${escape(spec.info.title)}</title>
+    ${description("description")}
+    ${description("og:description")}
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="api-reference-container"></div>
+    <script src="${escapeAttribute("https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.min.js")}" crossorigin></script>
+    <script>
+      window.Scalar.createApiReference(document.getElementById('api-reference-container'), {
+        ...${escapeJson({ _integration: "html" })},
+        content: ${escapeJson(spec)}
+      })
+    </script>
+  </body>
+</html>`);
+        return response;
+      }),
+    );
+  });