@confect/core 1.0.0-next.0

package/src/GroupPath.ts

@@ -0,0 +1,61 @@
+import type { Record } from "effect";
+import type * as GroupSpec from "./GroupSpec";
+
+/**
+ * Recursively generates paths for a group and its nested groups.
+ *
+ * - For a group with no subgroups, returns just the group name.
+ * - For a group with subgroups, returns the group name plus all possible paths through its direct subgroups.
+ */
+export type All<
+  Group extends GroupSpec.AnyWithProps,
+  Depth extends 1[] = [],
+> = Depth["length"] extends 15
+  ? string
+  : Group extends any
+    ? [GroupSpec.Groups<Group>] extends [never]
+      ? GroupSpec.Name<Group>
+      : GroupSpec.Name<Group> | AllHelper<Group, GroupSpec.Groups<Group>, Depth>
+    : never;
+
+type AllHelper<
+  Parent extends GroupSpec.AnyWithProps,
+  Groups_ extends GroupSpec.AnyWithProps,
+  Depth extends 1[] = [],
+> = Groups_ extends GroupSpec.AnyWithProps
+  ? `${GroupSpec.Name<Parent>}.${All<Groups_, [...Depth, 1]>}`
+  : never;
+
+/**
+ * Recursively extracts the group at the given dot-separated path.
+ * Path must match the format defined in `Path` above, e.g. "group" or "group.subgroup".
+ *
+ * @example
+ * ```ts
+ * type G = WithPath<RootGroup, "group.subgroup">;
+ * ```
+ */
+export type GroupAt<
+  Group,
+  Path extends string,
+> = Group extends GroupSpec.AnyWithProps
+  ? Path extends `${infer Head}.${infer Tail}`
+    ? Group extends { readonly name: Head }
+      ? Group extends {
+          readonly groups: Record.ReadonlyRecord<string, infer SubGroup>;
+        }
+        ? GroupAt<SubGroup, Tail>
+        : never
+      : never
+    : GroupSpec.WithName<Group, Path>
+  : never;
+
+export type SubGroupsAt<
+  Group extends GroupSpec.AnyWithProps,
+  GroupPath extends string,
+> =
+  GroupSpec.Groups<GroupAt<Group, GroupPath>> extends infer SubGroups
+    ? SubGroups extends GroupSpec.AnyWithProps
+      ? `${GroupPath}.${GroupSpec.Name<SubGroups>}`
+      : never
+    : never;

package/src/GroupSpec.ts

@@ -0,0 +1,120 @@
+import { Predicate, Record } from "effect";
+import type * as FunctionSpec from "./FunctionSpec";
+import { validateConfectFunctionIdentifier } from "./internal/utils";
+
+export const TypeId = "@confect/core/api/GroupSpec";
+export type TypeId = typeof TypeId;
+
+export const isGroupSpec = (u: unknown): u is Any =>
+  Predicate.hasProperty(u, TypeId);
+
+export interface GroupSpec<
+  Name_ extends string,
+  Functions_ extends FunctionSpec.AnyWithProps = never,
+  Groups_ extends AnyWithProps = never,
+> {
+  readonly [TypeId]: TypeId;
+  readonly name: Name_;
+  readonly functions: {
+    [FunctionName in FunctionSpec.Name<Functions_>]: FunctionSpec.WithName<
+      Functions_,
+      FunctionName
+    >;
+  };
+  readonly groups: {
+    [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;
+  };
+
+  addFunction<Function extends FunctionSpec.AnyWithProps>(
+    function_: Function,
+  ): GroupSpec<Name_, Functions_ | Function, Groups_>;
+
+  addGroup<Group extends AnyWithProps>(
+    group: Group,
+  ): GroupSpec<Name_, Functions_, Groups_ | Group>;
+}
+
+export interface Any {
+  readonly [TypeId]: TypeId;
+}
+
+export interface AnyWithProps
+  extends GroupSpec<string, FunctionSpec.AnyWithProps, AnyWithProps> {}
+
+export type Name<Group extends AnyWithProps> = Group["name"];
+
+export type Functions<Group extends AnyWithProps> =
+  Group["functions"][keyof Group["functions"]];
+
+export type Groups<Group extends AnyWithProps> =
+  Group["groups"][keyof Group["groups"]];
+
+export type GroupNames<Group extends AnyWithProps> = [Groups<Group>] extends [
+  never,
+]
+  ? never
+  : Name<Groups<Group>>;
+
+export type WithName<
+  Group extends AnyWithProps,
+  Name_ extends Name<Group>,
+> = Extract<Group, { readonly name: Name_ }>;
+
+const Proto = {
+  [TypeId]: TypeId,
+
+  addFunction<Function extends FunctionSpec.AnyWithProps>(
+    this: Any,
+    function_: Function,
+  ) {
+    const this_ = this as AnyWithProps;
+
+    return makeProto({
+      name: this_.name,
+      functions: Record.set(this_.functions, function_.name, function_),
+      groups: this_.groups,
+    });
+  },
+
+  addGroup<Group extends Any>(this: Any, group: Group) {
+    const this_ = this as AnyWithProps;
+    const group_ = group as unknown as AnyWithProps;
+
+    return makeProto({
+      name: this_.name,
+      functions: this_.functions,
+      groups: Record.set(this_.groups, group_.name, group_),
+    });
+  },
+};
+
+const makeProto = <
+  Name_ extends string,
+  Functions_ extends FunctionSpec.AnyWithProps,
+  Groups_ extends AnyWithProps,
+>({
+  name,
+  functions,
+  groups,
+}: {
+  name: Name_;
+  functions: Record.ReadonlyRecord<string, Functions_>;
+  groups: Record.ReadonlyRecord<string, Groups_>;
+}): GroupSpec<Name_, Functions_, Groups_> =>
+  Object.assign(Object.create(Proto), {
+    name,
+    functions,
+    groups,
+  });
+
+export const make = <const Name_ extends string>(
+  name: Name_,
+): GroupSpec<Name_> => {
+  validateConfectFunctionIdentifier(name);
+
+  return makeProto({
+    name,
+    functions: Record.empty(),
+    groups: Record.empty(),
+  });
+};

package/src/PaginationResult.ts

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+
+export const PaginationResult = <Doc extends Schema.Schema.AnyNoContext>(
+  Doc: Doc,
+) =>
+  Schema.Struct({
+    page: Schema.mutable(Schema.Array(Doc)),
+    isDone: Schema.Boolean,
+    continueCursor: Schema.String,
+    splitCursor: Schema.optionalWith(Schema.Union(Schema.String, Schema.Null), {
+      exact: true,
+    }),
+    pageStatus: Schema.optionalWith(
+      Schema.Union(
+        Schema.Literal("SplitRecommended"),
+        Schema.Literal("SplitRequired"),
+        Schema.Null,
+      ),
+      { exact: true },
+    ),
+  });

package/src/Ref.ts

@@ -0,0 +1,175 @@
+import type { FunctionType, FunctionVisibility } from "convex/server";
+import type { Schema } from "effect";
+import type * as FunctionSpec from "./FunctionSpec";
+
+export interface Ref<
+  _FunctionType extends FunctionType,
+  _FunctionVisibility extends FunctionVisibility,
+  _Args extends Schema.Schema.AnyNoContext,
+  _Returns extends Schema.Schema.AnyNoContext,
+> {
+  readonly _FunctionType?: _FunctionType;
+  readonly _FunctionVisibility?: _FunctionVisibility;
+  readonly _Args?: _Args;
+  readonly _Returns?: _Returns;
+}
+
+export interface Any extends Ref<any, any, any, any> {}
+
+export interface AnyInternal extends Ref<any, "internal", any, any> {}
+
+export interface AnyPublic extends Ref<any, "public", any, any> {}
+
+export interface AnyQuery
+  extends Ref<
+    "query",
+    FunctionVisibility,
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export interface AnyMutation
+  extends Ref<
+    "mutation",
+    FunctionVisibility,
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export interface AnyAction
+  extends Ref<
+    "action",
+    FunctionVisibility,
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export interface AnyPublicQuery
+  extends Ref<
+    "query",
+    "public",
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export interface AnyPublicMutation
+  extends Ref<
+    "mutation",
+    "public",
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export interface AnyPublicAction
+  extends Ref<
+    "action",
+    "public",
+    Schema.Schema.AnyNoContext,
+    Schema.Schema.AnyNoContext
+  > {}
+
+export type GetFunctionType<Ref_> =
+  Ref_ extends Ref<
+    infer FunctionType_,
+    infer _FunctionVisibility,
+    infer _Args,
+    infer _Returns
+  >
+    ? FunctionType_
+    : never;
+
+export type GetFunctionVisibility<Ref_> =
+  Ref_ extends Ref<
+    infer _FunctionType,
+    infer FunctionVisibility_,
+    infer _Args,
+    infer _Returns
+  >
+    ? FunctionVisibility_
+    : never;
+
+export type Args<Ref_> =
+  Ref_ extends Ref<
+    infer _FunctionType,
+    infer _FunctionVisibility,
+    infer Args_,
+    infer _Returns
+  >
+    ? Args_
+    : never;
+
+export type Returns<Ref_> =
+  Ref_ extends Ref<
+    infer _FunctionType,
+    infer _FunctionVisibility,
+    infer _Args,
+    infer Returns_
+  >
+    ? Returns_
+    : never;
+
+export type FromFunctionSpec<F extends FunctionSpec.AnyWithProps> = Ref<
+  FunctionSpec.GetFunctionType<F>,
+  FunctionSpec.GetFunctionVisibility<F>,
+  FunctionSpec.Args<F>,
+  FunctionSpec.Returns<F>
+>;
+
+export const make = <
+  FunctionType_ extends FunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends Schema.Schema.AnyNoContext,
+  Returns_ extends Schema.Schema.AnyNoContext,
+>(
+  /**
+   * This is a Convex "function name" of the format "myGroupDir/myGroupMod:myFunc".
+   */
+  convexFunctionName: string,
+  // TODO: Pull out all of the fields from the function spec except the name (we don't need it because we already have the convex function name) and spread them here
+  function_: FunctionSpec.FunctionSpec<
+    FunctionType_,
+    FunctionVisibility_,
+    string,
+    Args_,
+    Returns_
+  >,
+): Ref<FunctionType_, FunctionVisibility_, Args_, Returns_> =>
+  ({
+    [HiddenFunctionKey]: function_,
+    [HiddenConvexFunctionNameKey]: convexFunctionName,
+  }) as Ref<FunctionType_, FunctionVisibility_, Args_, Returns_>;
+
+// TODO: Is this hidden stuff necessary/useful still?
+const HiddenFunctionKey = "@confect/core/api/HiddenFunctionKey";
+type HiddenFunctionKey = typeof HiddenFunctionKey;
+type HiddenFunction<Ref_ extends Any> = FunctionSpec.FunctionSpec<
+  GetFunctionType<Ref_>,
+  GetFunctionVisibility<Ref_>,
+  string,
+  Args<Ref_>,
+  Returns<Ref_>
+>;
+
+export const getFunction = <
+  FunctionType_ extends FunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends Schema.Schema.AnyNoContext,
+  Returns_ extends Schema.Schema.AnyNoContext,
+  Ref_ extends Ref<FunctionType_, FunctionVisibility_, Args_, Returns_>,
+>(
+  ref: Ref_,
+): HiddenFunction<Ref_> => (ref as any)[HiddenFunctionKey];
+
+const HiddenConvexFunctionNameKey =
+  "@confect/core/api/HiddenConvexFunctionNameKey";
+type HiddenConvexFunctionNameKey = typeof HiddenConvexFunctionNameKey;
+type HiddenConvexFunctionName = string;
+
+export const getConvexFunctionName = <
+  FunctionType_ extends FunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends Schema.Schema.AnyNoContext,
+  Returns_ extends Schema.Schema.AnyNoContext,
+>(
+  ref: Ref<FunctionType_, FunctionVisibility_, Args_, Returns_>,
+): HiddenConvexFunctionName => (ref as any)[HiddenConvexFunctionNameKey];

package/src/Refs.ts

@@ -0,0 +1,99 @@
+import type { Types } from "effect";
+import { pipe, Record } from "effect";
+import type * as FunctionSpec from "./FunctionSpec";
+import type * as GroupSpec from "./GroupSpec";
+import * as Ref from "./Ref";
+import type * as Spec from "./Spec";
+
+export type Refs<
+  Spec_ extends Spec.AnyWithProps,
+  Predicate extends Ref.Any = Ref.Any,
+> = Types.Simplify<Helper<Spec.Groups<Spec_>, Predicate>>;
+
+type GroupRefs<
+  Group extends GroupSpec.AnyWithProps,
+  Predicate extends Ref.Any,
+> = Types.Simplify<
+  Helper<GroupSpec.Groups<Group>, Predicate> &
+    FilteredFunctions<GroupSpec.Functions<Group>, Predicate>
+>;
+
+type FilteredFunctions<
+  Functions extends FunctionSpec.AnyWithProps,
+  Predicate extends Ref.Any,
+> = {
+  [Name in FunctionSpec.Name<Functions> as FunctionSpec.WithName<
+    Functions,
+    Name
+  > extends infer F extends FunctionSpec.AnyWithProps
+    ? Ref.FromFunctionSpec<F> extends Predicate
+      ? Name
+      : never
+    : never]: FunctionSpec.WithName<Functions, Name> extends infer F extends
+    FunctionSpec.AnyWithProps
+    ? Ref.FromFunctionSpec<F>
+    : never;
+};
+
+type Helper<
+  Groups extends GroupSpec.AnyWithProps,
+  Predicate extends Ref.Any,
+> = {
+  [GroupName in GroupSpec.Name<Groups> as GroupSpec.WithName<
+    Groups,
+    GroupName
+  > extends infer Group extends GroupSpec.AnyWithProps
+    ? GroupRefs<Group, Predicate> extends Record<string, never>
+      ? never
+      : GroupName
+    : never]: GroupSpec.WithName<Groups, GroupName> extends infer Group extends
+    GroupSpec.AnyWithProps
+    ? GroupRefs<Group, Predicate>
+    : never;
+};
+
+type Any =
+  | {
+      readonly [key: string]: Any;
+    }
+  | Ref.Any;
+
+export const make = <Spec_ extends Spec.AnyWithProps>(
+  spec: Spec_,
+): {
+  all: Refs<Spec_>;
+  public: Refs<Spec_, Ref.AnyPublic>;
+  internal: Refs<Spec_, Ref.AnyInternal>;
+} => {
+  const refs = makeHelper(spec.groups);
+  return {
+    all: refs as Refs<Spec_>,
+    public: refs as Refs<Spec_, Ref.AnyPublic>,
+    internal: refs as Refs<Spec_, Ref.AnyInternal>,
+  };
+};
+
+const makeHelper = (
+  groups: Record.ReadonlyRecord<string, GroupSpec.Any>,
+  groupPath: string | null = null,
+): Any =>
+  pipe(
+    groups as Record.ReadonlyRecord<string, GroupSpec.AnyWithProps>,
+    Record.map((group) => {
+      const currentGroupPath = groupPath
+        ? `${groupPath}/${group.name}`
+        : group.name;
+
+      return Record.union(
+        makeHelper(group.groups, currentGroupPath),
+        Record.map(group.functions, (function_) =>
+          Ref.make(`${currentGroupPath}:${function_.name}`, function_),
+        ),
+        (_subGroup, _function) => {
+          throw new Error(
+            `Group and function at same level have same name ('${Ref.getConvexFunctionName(_function)}')`,
+          );
+        },
+      );
+    }),
+  );

package/src/Spec.ts

@@ -0,0 +1,52 @@
+import { Predicate, Record } from "effect";
+import type * as GroupSpec from "./GroupSpec";
+
+export const TypeId = "@confect/core/api/Spec";
+export type TypeId = typeof TypeId;
+
+export const isSpec = (u: unknown): u is AnyWithProps =>
+  Predicate.hasProperty(u, TypeId);
+
+export interface Spec<Groups_ extends GroupSpec.AnyWithProps = never> {
+  readonly [TypeId]: TypeId;
+  readonly groups: {
+    [GroupName in GroupSpec.Name<Groups_>]: GroupSpec.WithName<
+      Groups_,
+      GroupName
+    >;
+  };
+
+  add<Group extends GroupSpec.AnyWithProps>(
+    group: Group,
+  ): Spec<Groups_ | Group>;
+}
+
+export interface Any {
+  readonly [TypeId]: TypeId;
+}
+
+export interface AnyWithProps extends Spec<GroupSpec.AnyWithProps> {}
+
+export type Groups<Spec_ extends AnyWithProps> =
+  Spec_["groups"][keyof Spec_["groups"]];
+
+const Proto = {
+  [TypeId]: TypeId,
+
+  add<Group extends GroupSpec.AnyWithProps>(this: AnyWithProps, group: Group) {
+    return makeProto({
+      groups: Record.set(this.groups, group.name, group),
+    });
+  },
+};
+
+const makeProto = <Groups_ extends GroupSpec.AnyWithProps>({
+  groups,
+}: {
+  groups: Record.ReadonlyRecord<string, Groups_>;
+}): Spec<Groups_> =>
+  Object.assign(Object.create(Proto), {
+    groups,
+  });
+
+export const make = (): Spec => makeProto({ groups: {} });

package/src/SystemFields.ts

@@ -0,0 +1,51 @@
+import type {
+  Expand,
+  IdField,
+  SystemFields as NonIdSystemFields,
+} from "convex/server";
+import { Schema } from "effect";
+import * as GenericId from "./GenericId";
+
+type SystemFieldsSchema<TableName extends string> = Schema.Struct<{
+  _id: Schema.Schema<
+    GenericId.GenericId<TableName>,
+    GenericId.GenericId<TableName>,
+    never
+  >;
+  _creationTime: typeof Schema.Number;
+}>;
+
+/**
+ * Produces a schema for Convex system fields.
+ */
+export const SystemFields = <TableName extends string>(
+  tableName: TableName,
+): SystemFieldsSchema<TableName> =>
+  Schema.Struct({
+    _id: GenericId.GenericId(tableName),
+    _creationTime: Schema.Number,
+  });
+
+/**
+ * Extend a table schema with Convex system fields.
+ */
+export const extendWithSystemFields = <
+  TableName extends string,
+  TableSchema extends Schema.Schema.AnyNoContext,
+>(
+  tableName: TableName,
+  schema: TableSchema,
+): ExtendWithSystemFields<TableName, TableSchema> =>
+  Schema.extend(SystemFields(tableName), schema);
+
+/**
+ * Extend a table schema with Convex system fields at the type level.
+ */
+export type ExtendWithSystemFields<
+  TableName extends string,
+  TableSchema extends Schema.Schema.AnyNoContext,
+> = Schema.extend<SystemFieldsSchema<TableName>, TableSchema>;
+
+export type WithSystemFields<TableName extends string, Document> = Expand<
+  Readonly<IdField<TableName>> & Readonly<NonIdSystemFields> & Document
+>;