@confect/core 10.0.0-next.2 → 10.0.0-next.21

package/src/Spec.ts

@@ -2,7 +2,7 @@ import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
 import * as GroupSpec from "./GroupSpec";
 
-export const TypeId = "@confect/core/Spec";
+export const TypeId = "~@confect/core/Spec";
 export type TypeId = typeof TypeId;
 
 export const isSpec = (u: unknown): u is AnyWithProps =>
@@ -23,6 +23,7 @@ export interface Spec<Groups_ extends GroupSpec.AnyWithProps = never> {
       GroupName
     >;
   };
+  readonly "~Groups": Groups_;
 
   add<Group extends GroupSpec.AnyWithProps>(
     group: Group,
@@ -40,8 +41,7 @@ export interface Any {
 
 export interface AnyWithProps extends Spec<GroupSpec.AnyWithProps> {}
 
-export type Groups<Spec_ extends AnyWithProps> =
-  Spec_["groups"][keyof Spec_["groups"]];
+export type Groups<Spec_ extends AnyWithProps> = Spec_["~Groups"];
 
 const Proto = {
   [TypeId]: TypeId,
@@ -70,6 +70,6 @@ const makeProto = <Groups_ extends GroupSpec.AnyWithProps>({
 }): Spec<Groups_> =>
   Object.assign(Object.create(Proto), {
     groups,
-  });
+  }) as Spec<Groups_>;
 
 export const make = (): Spec => makeProto({ groups: {} });

package/src/SystemFields.ts

@@ -18,7 +18,7 @@ import * as GenericId from "./GenericId";
 export const SystemFields = <TableName extends string>(tableName: TableName) =>
   Schema.Struct({
     _id: GenericId.GenericId(tableName),
-    _creationTime: Schema.Number,
+    _creationTime: Schema.Finite,
   });
 
 /**
@@ -58,9 +58,9 @@ const splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {
  * output. Transformations construct fresh objects, so without this the system
  * fields would be dropped at every transformation step.
  */
-const wrapGetter = (
-  getter: SchemaGetter.Getter<any, any, any>,
-): SchemaGetter.Getter<any, any, any> =>
+const wrapGetter = <R>(
+  getter: SchemaGetter.Getter<any, any, R>,
+): SchemaGetter.Getter<any, any, R> =>
   new SchemaGetter.Getter((input, options) => {
     if (Option.isNone(input) || !Predicate.isObject(input.value)) {
       return getter.run(input, options);
@@ -191,9 +191,7 @@ export const extendWithSystemFields = <
     if (
       s.ast.encoding === undefined &&
       SchemaAST.isUnion(s.ast) &&
-      Array.isArray(
-        (s as Partial<Schema.Union<ReadonlyArray<Schema.Top>>>).members,
-      )
+      Array.isArray((s as { readonly members?: unknown }).members)
     ) {
       return Schema.Union(
         Array.map(
@@ -205,8 +203,7 @@ export const extendWithSystemFields = <
     if (
       s.ast.encoding === undefined &&
       SchemaAST.isObjects(s.ast) &&
-      typeof (s as Partial<Schema.Struct<Schema.Struct.Fields>>).mapFields ===
-        "function"
+      typeof (s as { readonly mapFields?: unknown }).mapFields === "function"
     ) {
       return Schema.fieldsAssign(system)(
         s as Schema.Struct<Schema.Struct.Fields>,

package/src/Table.ts

@@ -0,0 +1,426 @@
+import * as Lazy from "./Lazy";
+import * as SystemFields from "./SystemFields";
+import type { TableSchemaToTableValidator } from "./SchemaToValidator";
+import type {
+  SystemFields as ConvexSystemFields,
+  Expand,
+  GenericTableIndexes,
+  GenericTableSearchIndexes,
+  GenericTableVectorIndexes,
+  IndexTiebreakerField,
+  SearchIndexConfig,
+  VectorIndexConfig,
+} from "convex/server";
+import type { GenericValidator, Validator } from "convex/values";
+import * as Predicate from "effect/Predicate";
+import type * as Schema from "effect/Schema";
+
+export const TypeId = "~@confect/core/Table";
+export type TypeId = typeof TypeId;
+
+// -----------------------------------------------------------------------------
+// Predicates
+// -----------------------------------------------------------------------------
+//
+// Both bound `Table`s and `UnnamedTable` callables share the same `[TypeId]`
+// brand. They disambiguate by whether a `tableName` property is set: bound
+// tables have one, unnamed callables do not.
+//
+// The discriminator is `tableName` (not `name`) so it does not collide with
+// the built-in `Function.prototype.name` that every JS function carries.
+
+export const isTable = (u: unknown): u is Any =>
+  Predicate.hasProperty(u, TypeId) && Predicate.hasProperty(u, "tableName");
+
+export const isUnnamedTable = (u: unknown): u is UnnamedAny =>
+  Predicate.hasProperty(u, TypeId) && !Predicate.hasProperty(u, "tableName");
+
+// -----------------------------------------------------------------------------
+// Bound Table
+// -----------------------------------------------------------------------------
+//
+// A bound `Table` is the client-safe document schema: `Fields`, `Doc`, and
+// the index metadata records. The Convex deploy `tableDefinition` (which
+// value-imports `convex/server`) is produced separately by
+// `@confect/server/Table.tableDefinition`.
+
+export interface Table<
+  Name_ extends string,
+  TableSchema_ extends Schema.Codec<any, any>,
+  TableValidator_ extends GenericValidator =
+    TableSchemaToTableValidator<TableSchema_>,
+  Indexes_ extends GenericTableIndexes = {},
+  SearchIndexes_ extends GenericTableSearchIndexes = {},
+  VectorIndexes_ extends GenericTableVectorIndexes = {},
+> {
+  readonly [TypeId]: TypeId;
+  readonly tableName: Name_;
+  readonly Fields: TableSchema_;
+  readonly Doc: SystemFields.ExtendWithSystemFields<Name_, TableSchema_>;
+  readonly indexes: Indexes_;
+  readonly searchIndexes: SearchIndexes_;
+  readonly vectorIndexes: VectorIndexes_;
+  readonly "~TableValidator": TableValidator_;
+}
+
+export interface Any {
+  readonly [TypeId]: TypeId;
+  readonly tableName: string;
+}
+
+export type AnyWithProps = Table<
+  any,
+  Schema.Codec<any, any>,
+  GenericValidator,
+  GenericTableIndexes,
+  GenericTableSearchIndexes,
+  GenericTableVectorIndexes
+>;
+
+// -----------------------------------------------------------------------------
+// UnnamedTable (callable)
+// -----------------------------------------------------------------------------
+//
+// `Table.make(lazyFields)` returns an `UnnamedTable`: a callable that
+// produces a fully bound `Table` when invoked with a name. Chaining methods
+// (`.index`, `.searchIndex`, `.vectorIndex`) live here and return new
+// `UnnamedTable`s, accumulating plain index metadata records. The
+// user-supplied `lazyFields` callback is just carried through until first
+// access of `Fields` / `Doc` on a bound table. The codegen pipeline emits a
+// wrapper file per user-authored table that simply invokes the unnamed
+// callable with the filename basename.
+
+export interface UnnamedTable<
+  TableSchema_ extends Schema.Codec<any, any>,
+  TableValidator_ extends GenericValidator =
+    TableSchemaToTableValidator<TableSchema_>,
+  Indexes_ extends GenericTableIndexes = {},
+  SearchIndexes_ extends GenericTableSearchIndexes = {},
+  VectorIndexes_ extends GenericTableVectorIndexes = {},
+> {
+  <const Name_ extends string>(
+    tableName: Name_,
+  ): Table<
+    Name_,
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    VectorIndexes_
+  >;
+
+  readonly [TypeId]: TypeId;
+  readonly indexes: Indexes_;
+  readonly searchIndexes: SearchIndexes_;
+  readonly vectorIndexes: VectorIndexes_;
+  readonly "~TableValidator": TableValidator_;
+
+  index<
+    IndexName extends string,
+    FirstFieldPath extends ExtractFieldPaths<TableValidator_>,
+    RestFieldPaths extends ExtractFieldPaths<TableValidator_>[],
+  >(
+    name: IndexName,
+    fields: [FirstFieldPath, ...RestFieldPaths],
+  ): UnnamedTable<
+    TableSchema_,
+    TableValidator_,
+    Expand<
+      Indexes_ &
+        Record<
+          IndexName,
+          [FirstFieldPath, ...RestFieldPaths, IndexTiebreakerField]
+        >
+    >,
+    SearchIndexes_,
+    VectorIndexes_
+  >;
+
+  searchIndex<
+    IndexName extends string,
+    SearchField extends ExtractFieldPaths<TableValidator_>,
+    FilterFields extends ExtractFieldPaths<TableValidator_> = never,
+  >(
+    name: IndexName,
+    indexConfig: Expand<SearchIndexConfig<SearchField, FilterFields>>,
+  ): UnnamedTable<
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    Expand<
+      SearchIndexes_ &
+        Record<
+          IndexName,
+          {
+            searchField: SearchField;
+            filterFields: FilterFields;
+          }
+        >
+    >,
+    VectorIndexes_
+  >;
+
+  vectorIndex<
+    IndexName extends string,
+    VectorField extends ExtractFieldPaths<TableValidator_>,
+    FilterFields extends ExtractFieldPaths<TableValidator_> = never,
+  >(
+    name: IndexName,
+    indexConfig: Expand<VectorIndexConfig<VectorField, FilterFields>>,
+  ): UnnamedTable<
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    Expand<
+      VectorIndexes_ &
+        Record<
+          IndexName,
+          {
+            vectorField: VectorField;
+            dimensions: number;
+            filterFields: FilterFields;
+          }
+        >
+    >
+  >;
+}
+
+export interface UnnamedAny {
+  readonly [TypeId]: TypeId;
+}
+
+export type UnnamedAnyWithProps = UnnamedTable<
+  Schema.Codec<any, any>,
+  GenericValidator,
+  GenericTableIndexes,
+  GenericTableSearchIndexes,
+  GenericTableVectorIndexes
+>;
+
+// -----------------------------------------------------------------------------
+// Type extractors
+// -----------------------------------------------------------------------------
+
+export type Name<TableDef extends AnyWithProps> = TableDef["tableName"] &
+  string;
+
+export type TableSchema<TableDef extends AnyWithProps> = TableDef["Fields"];
+
+export type TableValidator<TableDef extends AnyWithProps> =
+  TableDef["~TableValidator"];
+
+export type Indexes<TableDef extends AnyWithProps> = TableDef["indexes"];
+
+export type SearchIndexes<TableDef extends AnyWithProps> =
+  TableDef["searchIndexes"];
+
+export type VectorIndexes<TableDef extends AnyWithProps> =
+  TableDef["vectorIndexes"];
+
+export type Doc<TableDef extends AnyWithProps> = TableDef["Doc"];
+
+export type Fields<TableDef extends AnyWithProps> = TableDef["Fields"];
+
+export type WithName<
+  TableDef extends AnyWithProps,
+  Name_ extends string,
+> = TableDef extends { readonly tableName: Name_ } ? TableDef : never;
+
+export type TablesRecord<Tables extends AnyWithProps> = {
+  readonly [TableName_ in Name<Tables>]: WithName<Tables, TableName_>;
+};
+
+// -----------------------------------------------------------------------------
+// Construction
+// -----------------------------------------------------------------------------
+//
+// `make` only stores the user-supplied `lazyFields` callback alongside any
+// chained index metadata. Neither `Fields` nor `Doc` is constructed until
+// first access on a bound `Table`. Each chain step is O(1) (plain object
+// spread of the metadata records) and never invokes the callback. Binding
+// via `unnamed(tableName)` installs lazy memoised getters for `Fields` and
+// `Doc` via `Lazy.defineProperty`, so the first access materialises the
+// value and replaces the getter with a plain data property — second-and-
+// subsequent accesses are observably indistinguishable from a plain
+// property and avoid all function-call overhead.
+
+interface UnnamedState<
+  TableSchema_ extends Schema.Codec<any, any>,
+  Indexes_ extends GenericTableIndexes,
+  SearchIndexes_ extends GenericTableSearchIndexes,
+  VectorIndexes_ extends GenericTableVectorIndexes,
+> {
+  readonly lazyFields: () => TableSchema_;
+  readonly indexes: Indexes_;
+  readonly searchIndexes: SearchIndexes_;
+  readonly vectorIndexes: VectorIndexes_;
+}
+
+const makeBound = <
+  Name_ extends string,
+  TableSchema_ extends Schema.Codec<any, any>,
+  TableValidator_ extends Validator<any, any, any>,
+  Indexes_ extends GenericTableIndexes,
+  SearchIndexes_ extends GenericTableSearchIndexes,
+  VectorIndexes_ extends GenericTableVectorIndexes,
+>(
+  tableName: Name_,
+  state: UnnamedState<TableSchema_, Indexes_, SearchIndexes_, VectorIndexes_>,
+): Table<
+  Name_,
+  TableSchema_,
+  TableValidator_,
+  Indexes_,
+  SearchIndexes_,
+  VectorIndexes_
+> => {
+  const bound = {
+    [TypeId]: TypeId as TypeId,
+    tableName,
+    indexes: state.indexes,
+    searchIndexes: state.searchIndexes,
+    vectorIndexes: state.vectorIndexes,
+  } as Table<
+    Name_,
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    VectorIndexes_
+  >;
+
+  Lazy.defineProperty(bound, "Fields", () => state.lazyFields());
+
+  Lazy.defineProperty(bound, "Doc", () =>
+    SystemFields.extendWithSystemFields(
+      tableName,
+      (bound as { Fields: TableSchema_ }).Fields,
+    ),
+  );
+
+  return bound;
+};
+
+const makeUnnamed = <
+  TableSchema_ extends Schema.Codec<any, any>,
+  TableValidator_ extends Validator<any, any, any>,
+  Indexes_ extends GenericTableIndexes,
+  SearchIndexes_ extends GenericTableSearchIndexes,
+  VectorIndexes_ extends GenericTableVectorIndexes,
+>(
+  state: UnnamedState<TableSchema_, Indexes_, SearchIndexes_, VectorIndexes_>,
+): UnnamedTable<
+  TableSchema_,
+  TableValidator_,
+  Indexes_,
+  SearchIndexes_,
+  VectorIndexes_
+> => {
+  type UnnamedTable_ = UnnamedTable<
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    VectorIndexes_
+  >;
+
+  type UnnamedTableFunction<FunctionName extends keyof UnnamedTable_> =
+    UnnamedTable_[FunctionName];
+
+  const bind = <const Name_ extends string>(
+    tableName: Name_,
+  ): Table<
+    Name_,
+    TableSchema_,
+    TableValidator_,
+    Indexes_,
+    SearchIndexes_,
+    VectorIndexes_
+  > =>
+    makeBound<
+      Name_,
+      TableSchema_,
+      TableValidator_,
+      Indexes_,
+      SearchIndexes_,
+      VectorIndexes_
+    >(tableName, state);
+
+  const index: UnnamedTableFunction<"index"> = (name, fields) =>
+    makeUnnamed({
+      lazyFields: state.lazyFields,
+      indexes: {
+        ...state.indexes,
+        [name]: fields,
+      } as any,
+      searchIndexes: state.searchIndexes,
+      vectorIndexes: state.vectorIndexes,
+    });
+
+  const searchIndex: UnnamedTableFunction<"searchIndex"> = (
+    name,
+    indexConfig,
+  ) =>
+    makeUnnamed({
+      lazyFields: state.lazyFields,
+      indexes: state.indexes,
+      searchIndexes: {
+        ...state.searchIndexes,
+        [name]: indexConfig,
+      } as any,
+      vectorIndexes: state.vectorIndexes,
+    });
+
+  const vectorIndex: UnnamedTableFunction<"vectorIndex"> = (
+    name,
+    indexConfig,
+  ) =>
+    makeUnnamed({
+      lazyFields: state.lazyFields,
+      indexes: state.indexes,
+      searchIndexes: state.searchIndexes,
+      vectorIndexes: {
+        ...state.vectorIndexes,
+        [name]: indexConfig,
+      } as any,
+    });
+
+  return Object.assign(bind, {
+    [TypeId]: TypeId as TypeId,
+    indexes: state.indexes,
+    searchIndexes: state.searchIndexes,
+    vectorIndexes: state.vectorIndexes,
+    index,
+    searchIndex,
+    vectorIndex,
+  }) as UnnamedTable_;
+};
+
+export const make = <const TableSchema_ extends Schema.Codec<any, any>>(
+  lazyFields: () => TableSchema_,
+): UnnamedTable<TableSchema_, TableSchemaToTableValidator<TableSchema_>> => {
+  type TableValidator_ = TableSchemaToTableValidator<TableSchema_>;
+  type UnnamedTable_ = UnnamedTable<TableSchema_, TableValidator_>;
+
+  return makeUnnamed<TableSchema_, TableValidator_, {}, {}, {}>({
+    lazyFields,
+    indexes: {},
+    searchIndexes: {},
+    vectorIndexes: {},
+  }) as UnnamedTable_;
+};
+
+// Vendored types from convex-js, partially modified. Ideally we could use these directly. See https://github.com/get-convex/convex-js/pull/14
+
+/**
+ * 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>> =
+  // Add in the system fields available in index definitions.
+  // This should be everything except for `_id` because thats added to indexes
+  // automatically.
+  T["fieldPaths"] | keyof ConvexSystemFields;

package/src/Types.ts

@@ -72,9 +72,15 @@ export type DeepMutable<T> =
                   : DeepMutable<T[K]>;
               };
 
-export type TypeError<Message extends string, T = never> = [Message, T];
-
-export type TypeDefect<Message extends string, T = never> = [Message, T];
+export interface TypeError<Message extends string, T = never> {
+  readonly "~@confect/core/Types/TypeError": Message;
+  readonly "~value"?: T;
+}
+
+export interface TypeDefect<Message extends string, T = never> {
+  readonly "~@confect/core/Types/TypeDefect": Message;
+  readonly "~value"?: T;
+}
 
 export type IsRecursive<T> = true extends DetectCycle<T> ? true : false;
 

package/src/index.ts

@@ -5,12 +5,16 @@ export * as GroupPath from "./GroupPath";
 export * as GroupSpec from "./GroupSpec";
 export * as Identifier from "./Identifier";
 export * as Lazy from "./Lazy";
+export * as MiddlewareSpec from "./MiddlewareSpec";
+export * as PaginationError from "./PaginationError";
+export * as PaginationOptions from "./PaginationOptions";
 export * as PaginationResult from "./PaginationResult";
 export * as Ref from "./Ref";
 export * as Refs from "./Refs";
-export * as Registry from "./Registry";
 export * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
+export * as SchemaToValidator from "./SchemaToValidator";
 export * as Spec from "./Spec";
 export * as SystemFields from "./SystemFields";
+export * as Table from "./Table";
 export * as Types from "./Types";
 export * as UserIdentity from "./UserIdentity";

package/dist/Registry.d.ts

@@ -1,24 +0,0 @@
-import * as Context from "effect/Context";
-import * as Ref from "effect/Ref";
-/**
- * Recursive tree that mirrors a `Spec`'s group structure. Leaves are the
- * per-function items written by each `FunctionImpl`'s layer initializer. The
- * leaf type is intentionally `unknown` here so `@confect/core` does not need
- * to know about `@confect/server`'s `RegistryItem` shape; producers and
- * consumers (the server runtime and the CLI's `implValidation`) narrow as
- * needed.
- */
-export interface RegistryItems {
-    readonly [key: string]: unknown | RegistryItems;
-}
-/**
- * Effect `Context.Reference` keyed by `@confect/core/Registry`. Lives in
- * `@confect/core` so `@confect/server` (which writes to it from
- * `FunctionImpl` initializers and reads it from `RegisteredFunctions`) and
- * `@confect/cli` (which inspects it during impl validation) can share the
- * exact same `Ref` instance by importing the same tag — without relying on
- * Effect's global default-value cache to align two separately-defined tags
- * by string key.
- */
-export declare const Registry: Context.Reference<Ref.Ref<RegistryItems>>;
-//# sourceMappingURL=Registry.d.ts.map

package/dist/Registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Registry.d.ts","sourceRoot":"","sources":["../src/Registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,GAAG,MAAM,YAAY,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,2CAKpB,CAAC"}

package/dist/Registry.js

@@ -1,19 +0,0 @@
-import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import * as Context from "effect/Context";
-import * as Ref from "effect/Ref";
-//#region src/Registry.ts
-var Registry_exports = /* @__PURE__ */ __exportAll({ Registry: () => Registry });
-/**
-* Effect `Context.Reference` keyed by `@confect/core/Registry`. Lives in
-* `@confect/core` so `@confect/server` (which writes to it from
-* `FunctionImpl` initializers and reads it from `RegisteredFunctions`) and
-* `@confect/cli` (which inspects it during impl validation) can share the
-* exact same `Ref` instance by importing the same tag — without relying on
-* Effect's global default-value cache to align two separately-defined tags
-* by string key.
-*/
-const Registry = Context.Reference("@confect/core/Registry", { defaultValue: () => Ref.makeUnsafe({}) });
-//#endregion
-export { Registry, Registry_exports };
-
-//# sourceMappingURL=Registry.js.map

package/dist/Registry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Registry.js","names":[],"sources":["../src/Registry.ts"],"sourcesContent":["import * as Context from \"effect/Context\";\nimport * as Ref from \"effect/Ref\";\n\n/**\n * Recursive tree that mirrors a `Spec`'s group structure. Leaves are the\n * per-function items written by each `FunctionImpl`'s layer initializer. The\n * leaf type is intentionally `unknown` here so `@confect/core` does not need\n * to know about `@confect/server`'s `RegistryItem` shape; producers and\n * consumers (the server runtime and the CLI's `implValidation`) narrow as\n * needed.\n */\nexport interface RegistryItems {\n  readonly [key: string]: unknown | RegistryItems;\n}\n\n/**\n * Effect `Context.Reference` keyed by `@confect/core/Registry`. Lives in\n * `@confect/core` so `@confect/server` (which writes to it from\n * `FunctionImpl` initializers and reads it from `RegisteredFunctions`) and\n * `@confect/cli` (which inspects it during impl validation) can share the\n * exact same `Ref` instance by importing the same tag — without relying on\n * Effect's global default-value cache to align two separately-defined tags\n * by string key.\n */\nexport const Registry = Context.Reference<Ref.Ref<RegistryItems>>(\n  \"@confect/core/Registry\",\n  {\n    defaultValue: () => Ref.makeUnsafe<RegistryItems>({}),\n  },\n);\n"],"mappings":";;;;;;;;;;;;;;AAwBA,MAAa,WAAW,QAAQ,UAC9B,0BACA,EACE,oBAAoB,IAAI,WAA0B,CAAC,CAAC,EACtD,CACF"}