@confect/core 9.0.0-next.5 → 9.0.0-next.6

package/src/{internal/utils.ts → Identifier.ts}

@@ -56,6 +56,12 @@ const RESERVED_CONVEX_FILE_NAMES = new Set(["schema", "http", "crons"]);
 
 const jsIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
+// Stricter than `jsIdentifierRegex`: tables cannot start with `_` (Convex
+// reserves leading underscores for system tables) or `$` (Convex's table
+// naming grammar does not accept it). Letters/digits/underscore only,
+// letter-leading.
+const tableNameRegex = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+
 const isReservedJsIdentifier = (identifier: string) =>
   RESERVED_JS_IDENTIFIERS.has(identifier);
 
@@ -65,6 +71,9 @@ const isReservedConvexFileName = (fileName: string) =>
 const matchesJsIdentifierPattern = (identifier: string) =>
   jsIdentifierRegex.test(identifier);
 
+const matchesTableNamePattern = (identifier: string) =>
+  tableNameRegex.test(identifier);
+
 export const validateConfectFunctionIdentifier = (identifier: string) => {
   if (!matchesJsIdentifierPattern(identifier)) {
     throw new Error(
@@ -84,3 +93,28 @@ export const validateConfectFunctionIdentifier = (identifier: string) => {
     );
   }
 };
+
+/**
+ * Validate that `identifier` is suitable as a Convex table name (and, equivalently,
+ * as a `confect/tables/<identifier>.ts` filename).
+ *
+ * Rules:
+ * - Must match `/^[A-Za-z][A-Za-z0-9_]*$/` — letter-leading, alphanumeric plus
+ *   underscore. No `$` (not a valid Convex table name character); no leading
+ *   `_` (Convex reserves `_<name>` for its system tables).
+ * - Must not be a reserved JavaScript identifier, so the name can also be used
+ *   as a binding name in generated code without escaping.
+ */
+export const validateConfectTableIdentifier = (identifier: string) => {
+  if (!matchesTableNamePattern(identifier)) {
+    throw new Error(
+      `Expected a valid Confect table identifier, but received: "${identifier}". Valid table identifiers must start with a letter and can only contain letters, numbers, and underscores. Leading underscores are reserved for Convex system tables.`,
+    );
+  }
+
+  if (isReservedJsIdentifier(identifier)) {
+    throw new Error(
+      `Expected a valid Confect table identifier, but received: "${identifier}". "${identifier}" is a reserved JavaScript identifier.`,
+    );
+  }
+};

package/src/Lazy.ts

@@ -0,0 +1,40 @@
+/**
+ * Install a lazy memoised property on `target`. The first access runs
+ * `compute()` and replaces the getter with a plain, non-writable data
+ * property whose value is the computed result. Subsequent accesses hit
+ * the V8 fast path for own data properties — no function call, identical
+ * returned reference — so first and second-and-subsequent accesses are
+ * observably indistinguishable.
+ *
+ * The replacement property is `enumerable: true` so the lazy property
+ * still participates in `Object.keys` / `JSON.stringify` after it
+ * materialises, matching the shape of a plain data property. The property
+ * is also `enumerable` before materialising, so presence checks
+ * (`"key" in target`, `Object.hasOwn(target, key)`) observe it without
+ * forcing the computation.
+ *
+ * This is the single shared implementation consumed across packages (e.g.
+ * `@confect/core`'s lazy `FunctionSpec` schemas and `@confect/server`'s lazy
+ * `Table` `Fields` / `Doc` / `tableDefinition`), so there is no chance of the
+ * two drifting apart.
+ */
+export const defineProperty = <T extends object, K extends PropertyKey>(
+  target: T,
+  key: K,
+  compute: () => unknown,
+): void => {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: true,
+    get(this: T) {
+      const value = compute();
+      Object.defineProperty(this, key, {
+        value,
+        writable: false,
+        enumerable: true,
+        configurable: false,
+      });
+      return value;
+    },
+  });
+};

package/src/Ref.ts

@@ -199,8 +199,7 @@ export const hasErrorSchema = (ref: Any): boolean =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag(
       "Confect",
-      (confectFunctionProvenance) =>
-        confectFunctionProvenance.error !== undefined,
+      (confectFunctionProvenance) => "error" in confectFunctionProvenance,
     ),
     Match.tag("Convex", () => false),
     Match.exhaustive,
@@ -296,7 +295,7 @@ export const decodeError = <Ref_ extends Any>(
 ): Effect.Effect<Option.Option<Error<Ref_>>, ParseResult.ParseError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      confectFunctionProvenance.error !== undefined
+      "error" in confectFunctionProvenance
         ? Effect.map(
             Schema.decode(confectFunctionProvenance.error)(encodedError),
             Option.some,
@@ -317,7 +316,7 @@ export const decodeErrorSync = <Ref_ extends Any>(
 ): Option.Option<Error<Ref_>> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      confectFunctionProvenance.error !== undefined
+      "error" in confectFunctionProvenance
         ? Option.some(
             Schema.decodeSync(confectFunctionProvenance.error)(
               encodedError,
@@ -336,7 +335,7 @@ export const maybeDecodeErrorSync = <Ref_ extends Any>(
   isConvexError(error)
     ? Match.value(ref.functionSpec.functionProvenance).pipe(
         Match.tag("Confect", (confectFunctionProvenance) =>
-          confectFunctionProvenance.error !== undefined
+          "error" in confectFunctionProvenance
             ? Schema.decodeSync(confectFunctionProvenance.error)(error.data)
             : error,
         ),

package/src/Spec.ts

@@ -1,7 +1,6 @@
-import { Array, Option, Predicate, Record, String } from "effect";
+import { Array, Option, Predicate, Record } from "effect";
 import * as GroupSpec from "./GroupSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
-import { validateConfectFunctionIdentifier } from "./internal/utils";
 
 export const TypeId = "@confect/core/Spec";
 export type TypeId = typeof TypeId;
@@ -33,13 +32,6 @@ export interface Spec<
       GroupName
     >;
   };
-  /**
-   * Mapping from an imported leaf `GroupSpec` reference to its full dot-path
-   * within this spec tree. Populated by codegen-emitted `_generated/spec.ts`
-   * via {@link Spec#addPath}; consumed by `FunctionImpl.make` /
-   * `GroupImpl.make` to resolve a spec's location without walking the tree.
-   */
-  readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;
 
   add<Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>>(
     group: Group,
@@ -52,18 +44,6 @@ export interface Spec<
     name: Name,
     group: Group,
   ): Spec<Runtime, Groups_ | GroupSpec.NamedAt<Group, Name>>;
-
-  /**
-   * Register the imported leaf `group` at `path` within this spec's path
-   * mapping. Returns a new `Spec` with one additional entry. The tree shape
-   * (`groups`) is unaffected — registration and tree assembly are
-   * independent steps, both performed by codegen in `_generated/spec.ts`.
-   *
-   * Re-registering the same group with the same path is a no-op (cheap
-   * defense for codegen watch-mode re-imports). Re-registering with a
-   * different path throws.
-   */
-  addPath(group: GroupSpec.AnyWithProps, path: string): Spec<Runtime, Groups_>;
 }
 
 export interface Any {
@@ -82,25 +62,6 @@ export interface AnyWithPropsWithRuntime<
 export type Groups<Spec_ extends AnyWithProps> =
   Spec_["groups"][keyof Spec_["groups"]];
 
-const validatePath = (path: string): void => {
-  if (path.length === 0) {
-    throw new Error(
-      "Expected a non-empty Confect group path, but received an empty string.",
-    );
-  }
-
-  const segments = String.split(path, ".");
-
-  for (const segment of segments) {
-    if (segment.length === 0) {
-      throw new Error(
-        `Expected a Confect group path made of dot-separated identifier segments, but received: "${path}".`,
-      );
-    }
-    validateConfectFunctionIdentifier(segment);
-  }
-};
-
 const Proto = {
   [TypeId]: TypeId,
 
@@ -108,7 +69,6 @@ const Proto = {
     return makeProto({
       runtime: this.runtime,
       groups: Record.set(this.groups, group.name, group),
-      paths: this.paths,
     });
   },
 
@@ -120,30 +80,6 @@ const Proto = {
     return makeProto({
       runtime: this.runtime,
       groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),
-      paths: this.paths,
-    });
-  },
-
-  addPath(this: AnyWithProps, group: GroupSpec.AnyWithProps, path: string) {
-    validatePath(path);
-
-    const existing = this.paths.get(group);
-    if (existing !== undefined) {
-      if (existing === path) {
-        return this;
-      }
-      throw new Error(
-        `Spec.addPath: the provided GroupSpec is already registered at "${existing}", but was re-registered at "${path}". Each GroupSpec must have at most one path.`,
-      );
-    }
-
-    const nextPaths = new Map(this.paths);
-    nextPaths.set(group, path);
-
-    return makeProto({
-      runtime: this.runtime,
-      groups: this.groups,
-      paths: nextPaths,
     });
   },
 };
@@ -154,32 +90,26 @@ const makeProto = <
 >({
   runtime,
   groups,
-  paths,
 }: {
   runtime: Runtime;
   groups: Record.ReadonlyRecord<string, Groups_>;
-  paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;
 }): Spec<Runtime, Groups_> =>
   Object.assign(Object.create(Proto), {
     runtime,
     groups,
-    paths,
   });
 
-const emptyPaths = (): ReadonlyMap<GroupSpec.AnyWithProps, string> => new Map();
-
 export const make = (): Spec<"Convex"> =>
-  makeProto({ runtime: "Convex", groups: {}, paths: emptyPaths() });
+  makeProto({ runtime: "Convex", groups: {} });
 
 export const makeNode = (): Spec<"Node"> =>
-  makeProto({ runtime: "Node", groups: {}, paths: emptyPaths() });
+  makeProto({ runtime: "Node", groups: {} });
 
 /**
- * Merges a Convex spec with an optional Node spec for use with `Api.make`.
+ * Merges a Convex spec with an optional Node spec into a single assembled
+ * spec (used by codegen to build `Refs.make` and to enumerate function paths).
  * When `nodeSpec` is provided, its groups are merged under a "node" namespace,
- * mirroring the structure used by `Refs.make`. The node spec's `paths`
- * entries are re-prefixed with `"node."` so they continue to identify the
- * same leaves at their new positions in the merged tree.
+ * mirroring the structure used by `Refs.make`.
  */
 export const merge = <
   ConvexSpec extends AnyWithPropsWithRuntime<"Convex">,
@@ -202,16 +132,8 @@ export const merge = <
     }),
   );
 
-  const paths = new Map(convexSpec.paths);
-  if (nodeSpec !== undefined) {
-    for (const [group, path] of nodeSpec.paths) {
-      paths.set(group, `node.${path}`);
-    }
-  }
-
   return Object.assign(Object.create(Proto), {
     runtime: "Convex" as const,
     groups,
-    paths,
   }) as AnyWithProps;
 };

package/src/index.ts

@@ -3,6 +3,8 @@ export * as FunctionSpec from "./FunctionSpec";
 export * as GenericId from "./GenericId";
 export * as GroupPath from "./GroupPath";
 export * as GroupSpec from "./GroupSpec";
+export * as Identifier from "./Identifier";
+export * as Lazy from "./Lazy";
 export * as PaginationResult from "./PaginationResult";
 export * as Ref from "./Ref";
 export * as Refs from "./Refs";

package/dist/internal/utils.d.ts

@@ -1,5 +0,0 @@
-//#region src/internal/utils.d.ts
-declare const validateConfectFunctionIdentifier: (identifier: string) => void;
-//#endregion
-export { validateConfectFunctionIdentifier };
-//# sourceMappingURL=utils.d.ts.map

package/dist/internal/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","names":[],"sources":["../../src/internal/utils.ts"],"mappings":";cAmEa,iCAAA,GAAqC,UAAA"}

package/dist/internal/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","names":[],"sources":["../../src/internal/utils.ts"],"sourcesContent":["const RESERVED_JS_IDENTIFIERS = new Set([\n  // Reserved keywords\n  \"break\",\n  \"case\",\n  \"catch\",\n  \"class\",\n  \"const\",\n  \"continue\",\n  \"debugger\",\n  \"default\",\n  \"delete\",\n  \"do\",\n  \"else\",\n  \"export\",\n  \"extends\",\n  \"finally\",\n  \"for\",\n  \"function\",\n  \"if\",\n  \"import\",\n  \"in\",\n  \"instanceof\",\n  \"new\",\n  \"return\",\n  \"super\",\n  \"switch\",\n  \"this\",\n  \"throw\",\n  \"try\",\n  \"typeof\",\n  \"var\",\n  \"void\",\n  \"while\",\n  \"with\",\n  \"yield\",\n  // Future reserved keywords\n  \"await\",\n  \"enum\",\n  \"implements\",\n  \"interface\",\n  \"let\",\n  \"package\",\n  \"private\",\n  \"protected\",\n  \"public\",\n  \"static\",\n  // Literal values that cannot be reassigned\n  \"null\",\n  \"true\",\n  \"false\",\n  // Global objects that shouldn't be shadowed\n  \"undefined\",\n]);\n\nconst RESERVED_CONVEX_FILE_NAMES = new Set([\"schema\", \"http\", \"crons\"]);\n\nconst jsIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;\n\nconst isReservedJsIdentifier = (identifier: string) =>\n  RESERVED_JS_IDENTIFIERS.has(identifier);\n\nconst isReservedConvexFileName = (fileName: string) =>\n  RESERVED_CONVEX_FILE_NAMES.has(fileName);\n\nconst matchesJsIdentifierPattern = (identifier: string) =>\n  jsIdentifierRegex.test(identifier);\n\nexport const validateConfectFunctionIdentifier = (identifier: string) => {\n  if (!matchesJsIdentifierPattern(identifier)) {\n    throw new Error(\n      `Expected a valid Confect function identifier, but received: \"${identifier}\". Valid identifiers must start with a letter, underscore, or dollar sign, and can only contain letters, numbers, underscores, or dollar signs.`,\n    );\n  }\n\n  if (isReservedJsIdentifier(identifier)) {\n    throw new Error(\n      `Expected a valid Confect function identifier, but received: \"${identifier}\". \"${identifier}\" is a reserved JavaScript identifier.`,\n    );\n  }\n\n  if (isReservedConvexFileName(identifier)) {\n    throw new Error(\n      `Expected a valid Confect function identifier, but received: \"${identifier}\". \"${identifier}\" is a reserved Convex file name.`,\n    );\n  }\n};\n"],"mappings":";AAAA,MAAM,0BAA0B,IAAI,IAAI;CAEtC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CAEA;CACD,CAAC;AAEF,MAAM,6BAA6B,IAAI,IAAI;CAAC;CAAU;CAAQ;CAAQ,CAAC;AAEvE,MAAM,oBAAoB;AAE1B,MAAM,0BAA0B,eAC9B,wBAAwB,IAAI,WAAW;AAEzC,MAAM,4BAA4B,aAChC,2BAA2B,IAAI,SAAS;AAE1C,MAAM,8BAA8B,eAClC,kBAAkB,KAAK,WAAW;AAEpC,MAAa,qCAAqC,eAAuB;AACvE,KAAI,CAAC,2BAA2B,WAAW,CACzC,OAAM,IAAI,MACR,gEAAgE,WAAW,iJAC5E;AAGH,KAAI,uBAAuB,WAAW,CACpC,OAAM,IAAI,MACR,gEAAgE,WAAW,MAAM,WAAW,wCAC7F;AAGH,KAAI,yBAAyB,WAAW,CACtC,OAAM,IAAI,MACR,gEAAgE,WAAW,MAAM,WAAW,mCAC7F"}