Add typed FieldMask to sdk-core

Introduces FieldMask<T> in @databricks/sdk-core/wkt with a
schema-validated `build` entry point and a wire-format `toString()`.
FieldMaskSchema and FieldMaskSchemaField describe a message's
FieldMask-reachable fields, including lazy `() => FieldMaskSchema`
children so recursive and mutually-recursive proto messages can
describe themselves without temporal-dead-zone or forward-reference
pitfalls.

`FieldMask.build` validates every camelCase path segment-by-segment,
throws on unknown fields or descents past scalar leaves, translates to
wire format, and stores the result privately. `toString()` joins the
stored wire paths with commas. Construction is private; generated
per-message factories (landing in a follow-up) are the only sanctioned
entry point.

Tests are table-driven (`it.each`) with two groups: valid paths that
translate and serialize, and invalid paths that throw with a
message-scoped error.

Co-authored-by: Isaac

Author: parthban-db

packages/core/src/wkt/fieldmask.ts

@@ -1,49 +1,8 @@
-// True if any property of T is callable, indicating a class instance (e.g.
-// Temporal.Instant, Date) rather than a plain data interface.
-type HasMethods<T> = true extends {
-  [K in keyof T]-?: NonNullable<T[K]> extends (...args: never[]) => unknown
-    ? true
-    : never;
-}[keyof T]
-  ? true
-  : false;
-
-/**
- * Utility type that derives all valid dot-separated field paths from a
- * TypeScript interface. Provides compile-time path validation for
- * {@link FieldMask}.
- *
- * Recursion stops at arrays, index signatures (Record/Map), and class
- * instances with methods (e.g. Temporal.Instant, Date). These are treated
- * as leaf nodes.
- *
- * @example
- * ```ts
- * interface Cluster {
- *   name: string;
- *   config: {numWorkers: number; scaling: {min: number}};
- * }
- * // "name" | "config" | "config.numWorkers" | "config.scaling" | "config.scaling.min"
- * type ClusterPaths = FieldPaths<Cluster>;
- * ```
- */
-export type FieldPaths<T, Prefix extends string = ''> = {
-  [K in keyof T & string]: NonNullable<T[K]> extends unknown[]
-    ? `${Prefix}${K}` // Array field — leaf, do not recurse.
-    : NonNullable<T[K]> extends Record<string, unknown>
-      ? string extends keyof NonNullable<T[K]>
-        ? `${Prefix}${K}` // Index signature (Record/Map) — leaf, do not recurse.
-        : HasMethods<NonNullable<T[K]>> extends true
-          ? `${Prefix}${K}` // Class instance with methods — leaf, do not recurse.
-          : `${Prefix}${K}` | FieldPaths<NonNullable<T[K]>, `${Prefix}${K}.`>
-      : `${Prefix}${K}`;
-}[keyof T & string];
-
 // Remove duplicates and paths subsumed by a parent (e.g. "config" subsumes
 // "config.numWorkers").
-function normalize<P extends string>(paths: P[]): P[] {
+function normalize(paths: string[]): string[] {
   const unique = [...new Set(paths)].sort();
-  const result: P[] = [];
+  const result: string[] = [];
   for (const path of unique) {
     const isSubsumed = result.some(existing => path.startsWith(existing + '.'));
     if (!isSubsumed) {
@@ -54,33 +13,125 @@ function normalize<P extends string>(paths: P[]): P[] {
 }
 
 /**
- * A type-safe field mask implementing google.protobuf.FieldMask semantics.
- * Provides compile-time path validation via {@link FieldPaths}. Paths are
- * always normalized: duplicates and paths subsumed by a parent are removed.
+ * One field entry in a {@link FieldMaskSchema}: its wire-format name and,
+ * for message-typed fields, a lazy reference to the nested message's
+ * schema. Array, map, enum, and scalar fields omit `children`.
+ */
+export interface FieldMaskSchemaField {
+  readonly wire: string;
+  readonly children?: () => FieldMaskSchema;
+}
+
+/**
+ * Structural description of one message's FieldMask-reachable fields.
+ * Maps each camelCase field name to its wire-format name and, for
+ * message-typed fields, a lazy `() => FieldMaskSchema` reference that
+ * lets recursive and mutually-recursive messages describe themselves
+ * without temporal-dead-zone pitfalls.
+ */
+export type FieldMaskSchema = Readonly<Record<string, FieldMaskSchemaField>>;
+
+// Walk a dot-separated camelCase path against a schema, returning the
+// equivalent wire-format path. Returns `undefined` when any segment
+// fails: a name that isn't a field of the current message, or a
+// non-terminal segment that doesn't reference another message. Kept
+// module-private — callers go through `FieldMask.build`, which is the
+// only sanctioned construction path.
+function walkFieldMaskPath(
+  schema: FieldMaskSchema,
+  path: string
+): string | undefined {
+  const segments = path.split('.');
+  const wireSegments: string[] = [];
+  let current: FieldMaskSchema = schema;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    // Existence check before lookup — `current[seg]` is typed as
+    // FieldMaskSchemaField without noUncheckedIndexedAccess, so an
+    // undefined check downstream would be flagged "unnecessary".
+    if (!(seg in current)) return undefined;
+    const field = current[seg];
+    wireSegments.push(field.wire);
+    if (i < segments.length - 1) {
+      if (field.children === undefined) return undefined;
+      current = field.children();
+    }
+  }
+  return wireSegments.join('.');
+}
+
+/**
+ * A field mask implementing google.protobuf.FieldMask semantics.
+ *
+ * Every mask is tagged with the message type it targets (`T`) so that
+ * generated client methods reject a mask built for the wrong message at
+ * compile time. Users never construct a `FieldMask` directly: the
+ * constructor is private and the only construction path is a generated
+ * per-message factory (e.g. `alertFieldMask(...)`) that delegates to
+ * `FieldMask.build`. Build validates every path against the target
+ * message's schema and throws synchronously on an unknown path, so
+ * typos fail at the call site rather than silently on the wire.
+ *
+ * The wire-format translation happens once, inside `build`, and the
+ * resulting wire-format paths are stored on the instance. `toString()`
+ * joins them with commas when the mask is serialized onto the wire.
  *
- * @example
- * ```ts
- * const mask = FieldMask.of<FieldPaths<Cluster>>(
- *   'displayName',
- *   'config.numWorkers'
- * );
- * ```
+ * The camelCase paths the caller passed in are not retained. Treat the
+ * mask as an opaque, immutable handle: construct with a factory, pass
+ * to a client method, let the SDK serialize it. `paths` is kept
+ * `private readonly` as a compile-time hint; it's not meant to be
+ * accessed from outside the class.
  */
-export class FieldMask<TPath extends string = string> {
-  /** The list of field paths in this mask. */
-  readonly paths: TPath[];
+export class FieldMask<T = unknown> {
+  // Phantom marker: keeps `FieldMask<Alert>` and `FieldMask<Query>`
+  // compile-time distinct under TypeScript's otherwise-structural
+  // typing. Never set at runtime.
+  declare private readonly _tag: T;
 
-  private constructor(paths: TPath[]) {
-    this.paths = normalize(paths);
+  // Stored post-translation, normalized wire-format paths. Marked
+  // `private readonly` so the TS compiler rejects external access and
+  // internal reassignment; callers should treat the mask as opaque and
+  // interact through the factory and `toString()`.
+  private readonly paths: string[];
+
+  private constructor(paths: string[]) {
+    this.paths = paths;
   }
 
-  /** Create a field mask from one or more paths. */
-  static of<P extends string>(...paths: P[]): FieldMask<P> {
-    return new FieldMask(paths);
+  /**
+   * Build a FieldMask from camelCase paths against the target message's
+   * schema. Validates every path by walking each segment through the
+   * schema and throws `Unknown field path "<p>"` on the first segment
+   * that names an unknown field or descends past a scalar leaf. On
+   * success, the paths are normalized (dedup + subsumption), translated
+   * to wire format, and stored on the instance.
+   *
+   * Reserved for generated per-message factories; user code should call
+   * the factory (e.g. `alertFieldMask(...)`), which supplies the
+   * schema before delegating here.
+   *
+   * @internal
+   */
+  static build<T>(paths: string[], schema: FieldMaskSchema): FieldMask<T> {
+    const normalized = normalize(paths);
+    const wire: string[] = [];
+    for (const p of normalized) {
+      const w = walkFieldMaskPath(schema, p);
+      if (w === undefined) {
+        throw new Error(`Unknown field path "${p}"`);
+      }
+      wire.push(w);
+    }
+    return new FieldMask<T>(wire);
   }
 
-  /** Return a new mask with additional paths appended. */
-  append(...paths: TPath[]): FieldMask<TPath> {
-    return new FieldMask([...this.paths, ...paths]);
+  /**
+   * Serialize the mask to the wire-format string the server expects: a
+   * comma-separated list of field paths in the message's wire naming
+   * (proto snake_case for Databricks). The wire paths were computed at
+   * construction time; this method just joins them.
+   */
+  toString(): string {
+    return this.paths.join(',');
   }
 }

packages/core/src/wkt/index.ts

@@ -1,3 +1,3 @@
 export {FieldMask} from './fieldmask';
-export type {FieldPaths} from './fieldmask';
+export type {FieldMaskSchema, FieldMaskSchemaField} from './fieldmask';
 export type {JsonValue, JsonObject} from './value';