@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/src/view.ts

@@ -1,629 +0,0 @@
-/**
- * VibeORM Views — Read-only scoped client with field-level restrictions.
- *
- * Views restrict which fields are returned by default, provide a `reveal`
- * keyword for explicit opt-in to extra fields, and enforce serialization
- * safety via toJSON() that excludes revealed fields.
- */
-
-import type {
-  ModelMeta,
-  ModelMetaMap,
-  ModelSchemas,
-  ValidationSchema,
-} from "./types.ts";
-import { getModelByNameMap } from "./types.ts";
-
-// ─── Types ────────────────────────────────────────────────────────
-
-/**
- * View definition: maps camelCase model keys to sets of allowed field names.
- * Example: { user: { id: true, name: true }, post: { id: true, title: true } }
- */
-export type ViewDefinition = Record<string, Record<string, true>>;
-
-// ─── ViewResult Class ─────────────────────────────────────────────
-
-/**
- * Wraps a query result record with serialization safety.
- *
- * - All fields (view + revealed) are accessible as direct properties.
- * - `toJSON()` excludes revealed fields (called by JSON.stringify).
- * - `$unsafe()` returns a plain object with ALL fields.
- *
- * Internal tracking (`_revealedFields`, `$unsafe`, `toJSON`) is non-enumerable
- * so it doesn't appear in Object.keys(), for...in, or spread.
- */
-export class ViewResult {
-  /** Allow dynamic property access for view/revealed fields. */
-  [key: string]: unknown;
-
-  /** @internal — set of field names that were revealed (non-enumerable). */
-  declare readonly _revealedFields: ReadonlySet<string>;
-  /** @internal — set of field names that are relation fields (non-enumerable). */
-  declare readonly _relationFields: ReadonlySet<string>;
-
-  constructor(params: {
-    record: Record<string, unknown>;
-    viewFields: Record<string, true>;
-    revealedFields: Record<string, true>;
-    relationFields?: Set<string>;
-  }) {
-    const { record, viewFields, revealedFields, relationFields } = params;
-
-    // Track which fields are revealed
-    const revealedSet = new Set(Object.keys(revealedFields));
-    Object.defineProperty(this, "_revealedFields", {
-      value: revealedSet,
-      enumerable: false,
-      writable: false,
-      configurable: false,
-    });
-
-    // Track relation field names
-    Object.defineProperty(this, "_relationFields", {
-      value: relationFields ?? new Set<string>(),
-      enumerable: false,
-      writable: false,
-      configurable: false,
-    });
-
-    // Assign all view + revealed fields as enumerable properties
-    const allowedFields = new Set([
-      ...Object.keys(viewFields),
-      ...Object.keys(revealedFields),
-    ]);
-
-    for (const key of allowedFields) {
-      if (key in record) {
-        (this as Record<string, unknown>)[key] = record[key];
-      }
-    }
-
-    // Also assign relation fields that may be present
-    if (relationFields) {
-      for (const relName of relationFields) {
-        if (relName in record) {
-          (this as Record<string, unknown>)[relName] = record[relName];
-        }
-      }
-    }
-  }
-
-  /**
-   * Returns a plain object with only view fields (excludes revealed fields).
-   * Called automatically by JSON.stringify().
-   */
-  toJSON(): Record<string, unknown> {
-    const obj: Record<string, unknown> = {};
-    for (const key of Object.keys(this)) {
-      if (this._revealedFields.has(key)) continue;
-      const value = (this as Record<string, unknown>)[key];
-      if (value instanceof ViewResult) {
-        obj[key] = value.toJSON();
-      } else if (Array.isArray(value)) {
-        obj[key] = value.map((item) =>
-          item instanceof ViewResult ? item.toJSON() : item
-        );
-      } else {
-        obj[key] = value;
-      }
-    }
-    return obj;
-  }
-
-  /**
-   * Returns a plain object with ALL fields (view + revealed).
-   * Use this as an escape hatch when you need the full data.
-   */
-  $unsafe(): Record<string, unknown> {
-    const obj: Record<string, unknown> = {};
-    for (const key of Object.keys(this)) {
-      const value = (this as Record<string, unknown>)[key];
-      if (value instanceof ViewResult) {
-        obj[key] = value.$unsafe();
-      } else if (Array.isArray(value)) {
-        obj[key] = value.map((item) =>
-          item instanceof ViewResult ? item.$unsafe() : item
-        );
-      } else {
-        obj[key] = value;
-      }
-    }
-    return obj;
-  }
-}
-
-// Make $unsafe non-enumerable on prototype (toJSON is already non-enumerable by default on prototype)
-Object.defineProperty(ViewResult.prototype, "$unsafe", {
-  ...Object.getOwnPropertyDescriptor(ViewResult.prototype, "$unsafe"),
-  enumerable: false,
-});
-
-Object.defineProperty(ViewResult.prototype, "toJSON", {
-  ...Object.getOwnPropertyDescriptor(ViewResult.prototype, "toJSON"),
-  enumerable: false,
-});
-
-// ─── Result Wrapping ──────────────────────────────────────────────
-
-/**
- * Wrap raw query result records into ViewResult instances.
- */
-export function wrapResultsWithView(params: {
-  records: Record<string, unknown>[];
-  viewFields: Record<string, true>;
-  revealedFields: Record<string, true>;
-  viewDefinition: ViewDefinition;
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-}): ViewResult[] {
-  const { records, viewFields, revealedFields, viewDefinition, modelMeta, allModelsMeta } = params;
-  const modelMap = getModelByNameMap({ allModelsMeta });
-
-  // Build set of relation field names present on this model
-  const relationFieldSet = new Set<string>();
-  for (const rel of modelMeta.relationFields) {
-    relationFieldSet.add(rel.name);
-  }
-
-  return records.map((record) => {
-    // Recursively wrap relation fields
-    const wrappedRecord: Record<string, unknown> = { ...record };
-
-    for (const rel of modelMeta.relationFields) {
-      const relValue = record[rel.name];
-      if (relValue === undefined || relValue === null) continue;
-
-      // Find the related model's camelCase key in allModelsMeta
-      const relatedModelMeta = modelMap.get(rel.relatedModel);
-      if (!relatedModelMeta) continue;
-
-      // Find the camelCase key for this related model in the view definition
-      const relatedViewKey = findModelKeyInMeta({
-        modelName: rel.relatedModel,
-        allModelsMeta,
-      });
-      const relatedViewFields = relatedViewKey
-        ? viewDefinition[relatedViewKey]
-        : undefined;
-
-      if (relatedViewFields) {
-        // Relation is in view definition — restrict its fields
-        if (Array.isArray(relValue)) {
-          wrappedRecord[rel.name] = wrapResultsWithView({
-            records: relValue as Record<string, unknown>[],
-            viewFields: relatedViewFields,
-            revealedFields: extractNestedReveal({ args: {}, relationName: rel.name }),
-            viewDefinition,
-            modelMeta: relatedModelMeta,
-            allModelsMeta,
-          });
-        } else if (typeof relValue === "object") {
-          const wrapped = wrapResultsWithView({
-            records: [relValue as Record<string, unknown>],
-            viewFields: relatedViewFields,
-            revealedFields: extractNestedReveal({ args: {}, relationName: rel.name }),
-            viewDefinition,
-            modelMeta: relatedModelMeta,
-            allModelsMeta,
-          });
-          wrappedRecord[rel.name] = wrapped[0] ?? null;
-        }
-      }
-      // If relation is NOT in view definition, leave as-is (no restriction)
-    }
-
-    return new ViewResult({
-      record: wrappedRecord,
-      viewFields,
-      revealedFields,
-      relationFields: relationFieldSet,
-    });
-  });
-}
-
-/**
- * Extract the nested reveal fields for a specific relation from the args.
- * For now returns empty — reveal handling is done at args merging time.
- */
-function extractNestedReveal(_params: {
-  args: Record<string, unknown>;
-  relationName: string;
-}): Record<string, true> {
-  return {};
-}
-
-/**
- * Find the camelCase key for a PascalCase model name in allModelsMeta.
- */
-function findModelKeyInMeta(params: {
-  modelName: string;
-  allModelsMeta: ModelMetaMap;
-}): string | undefined {
-  for (const [key, meta] of Object.entries(params.allModelsMeta)) {
-    if (meta.name === params.modelName) return key;
-  }
-  return undefined;
-}
-
-// ─── Args Merging ─────────────────────────────────────────────────
-
-/**
- * Merge view field definitions with user-provided args.
- *
- * This injects the view's field set as a `select`, handles `reveal`
- * by merging extra fields into the SQL select, and recursively
- * restricts relation includes.
- */
-export function mergeViewArgs(params: {
-  args: Record<string, unknown>;
-  viewFields: Record<string, true>;
-  viewDefinition: ViewDefinition;
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-}): {
-  mergedArgs: Record<string, unknown>;
-  revealedFields: Record<string, true>;
-} {
-  const { args, viewFields, viewDefinition, modelMeta, allModelsMeta } = params;
-  const modelMap = getModelByNameMap({ allModelsMeta });
-
-  // Extract reveal from args
-  const reveal = (args.reveal ?? {}) as Record<string, boolean>;
-  const revealedFields: Record<string, true> = {};
-  for (const [key, val] of Object.entries(reveal)) {
-    if (val === true) {
-      revealedFields[key] = true;
-    }
-  }
-
-  // Build the effective select
-  let effectiveSelect: Record<string, true>;
-
-  const userSelect = args.select as Record<string, boolean> | undefined;
-  if (userSelect) {
-    // User select narrows within view fields — only allow keys in viewFields
-    effectiveSelect = {};
-    for (const [key, val] of Object.entries(userSelect)) {
-      if (val === true && key in viewFields) {
-        effectiveSelect[key] = true;
-      }
-    }
-  } else {
-    // Default: use all view fields
-    effectiveSelect = { ...viewFields };
-  }
-
-  // Merge revealed fields into effective select (they go to SQL but are tracked separately)
-  for (const key of Object.keys(revealedFields)) {
-    effectiveSelect[key] = true;
-  }
-
-  // Process includes — restrict relation fields by view definition
-  const include = args.include as Record<string, unknown> | undefined;
-  let mergedInclude: Record<string, unknown> | undefined;
-
-  if (include) {
-    mergedInclude = {};
-    for (const [relName, relArgs] of Object.entries(include)) {
-      if (relName === "_count") {
-        // Pass through _count unchanged
-        mergedInclude[relName] = relArgs;
-        continue;
-      }
-
-      // Find the relation's model
-      const relField = modelMeta.relationFields.find((r) => r.name === relName);
-      if (!relField) {
-        mergedInclude[relName] = relArgs;
-        continue;
-      }
-
-      const relatedModelMeta = modelMap.get(relField.relatedModel);
-      if (!relatedModelMeta) {
-        mergedInclude[relName] = relArgs;
-        continue;
-      }
-
-      // Find view fields for the related model
-      const relatedViewKey = findModelKeyInMeta({
-        modelName: relField.relatedModel,
-        allModelsMeta,
-      });
-      const relatedViewFields = relatedViewKey
-        ? viewDefinition[relatedViewKey]
-        : undefined;
-
-      if (!relatedViewFields) {
-        // Relation not in view definition — pass through unchanged
-        mergedInclude[relName] = relArgs;
-        continue;
-      }
-
-      if (relArgs === true) {
-        // include: { posts: true } → include: { posts: { select: <viewFields> } }
-        mergedInclude[relName] = { select: { ...relatedViewFields } };
-      } else if (typeof relArgs === "object" && relArgs !== null) {
-        const nestedArgs = relArgs as Record<string, unknown>;
-        const nestedReveal = (nestedArgs.reveal ?? {}) as Record<string, boolean>;
-        const nestedRevealedFields: Record<string, true> = {};
-        for (const [key, val] of Object.entries(nestedReveal)) {
-          if (val === true) {
-            nestedRevealedFields[key] = true;
-          }
-        }
-
-        // Build nested select from view fields + nested reveal
-        const nestedSelect: Record<string, true> = { ...relatedViewFields };
-        for (const key of Object.keys(nestedRevealedFields)) {
-          nestedSelect[key] = true;
-        }
-
-        // Preserve other nested args (where, orderBy, take, skip, etc.)
-        const preservedArgs: Record<string, unknown> = {};
-        for (const [key, val] of Object.entries(nestedArgs)) {
-          if (key !== "reveal" && key !== "select") {
-            preservedArgs[key] = val;
-          }
-        }
-
-        // Handle nested includes recursively
-        if (nestedArgs.include) {
-          const nestedInclude = mergeViewArgs({
-            args: { include: nestedArgs.include },
-            viewFields: relatedViewFields,
-            viewDefinition,
-            modelMeta: relatedModelMeta,
-            allModelsMeta,
-          });
-          preservedArgs.include = (nestedInclude.mergedArgs as Record<string, unknown>).include;
-          // When there's a nested include, DON'T use select — use include + omit approach
-          // Actually, select and include conflict. If there's a nested include,
-          // we need to let include handle it and not use select
-          mergedInclude[relName] = {
-            ...preservedArgs,
-          };
-          continue;
-        }
-
-        mergedInclude[relName] = {
-          select: nestedSelect,
-          ...preservedArgs,
-        };
-      }
-    }
-  }
-
-  // Build the merged args
-  const mergedArgs: Record<string, unknown> = {};
-
-  // Copy through non-view-specific args
-  for (const [key, val] of Object.entries(args)) {
-    if (key !== "select" && key !== "reveal" && key !== "include" && key !== "omit") {
-      mergedArgs[key] = val;
-    }
-  }
-
-  // Set the effective select
-  mergedArgs.select = effectiveSelect;
-
-  // Set include if present
-  if (mergedInclude && Object.keys(mergedInclude).length > 0) {
-    // When we have both select and include, we need to also include relation
-    // keys in the select so they don't get filtered out
-    for (const relName of Object.keys(mergedInclude)) {
-      (mergedArgs.select as Record<string, unknown>)[relName] = mergedInclude[relName];
-    }
-  }
-
-  return { mergedArgs, revealedFields };
-}
-
-// ─── Zod Safety Net ───────────────────────────────────────────────
-
-/**
- * Build a picked Zod schema that only allows the specified fields.
- * Uses Zod v4's .pick() method via duck-typing.
- */
-export function buildPickedSchema(params: {
-  schema: ValidationSchema;
-  fields: Record<string, true>;
-}): ValidationSchema | undefined {
-  const { schema, fields } = params;
-
-  // Duck-type check: does the schema have .pick()?
-  const schemaWithPick = schema as unknown as {
-    pick?: (fields: Record<string, true>) => ValidationSchema;
-  };
-
-  if (typeof schemaWithPick.pick === "function") {
-    try {
-      return schemaWithPick.pick(fields);
-    } catch {
-      // If .pick() fails (e.g., invalid fields), fall back to no safety net
-      return undefined;
-    }
-  }
-
-  return undefined;
-}
-
-/**
- * Validate records through the view's picked schema.
- * Returns parsed data (with extra fields stripped) on success.
- * On failure, returns the original records (defense-in-depth, not critical path).
- */
-export function applyViewSchemaFilter(params: {
-  records: Record<string, unknown>[];
-  viewSchema: ValidationSchema | undefined;
-}): Record<string, unknown>[] {
-  const { records, viewSchema } = params;
-  if (!viewSchema) return records;
-
-  return records.map((record) => {
-    const result = viewSchema.safeParse(record);
-    if (result.success) {
-      return result.data as Record<string, unknown>;
-    }
-    // Safety net failed — return original record (the ViewResult wrapper
-    // will still restrict what's visible)
-    return record;
-  });
-}
-
-// ─── View Delegate Creation ───────────────────────────────────────
-
-/** Read operations exposed on view delegates. */
-const VIEW_READ_OPS = [
-  "findMany",
-  "findFirst",
-  "findUnique",
-  "findUniqueOrThrow",
-  "findFirstOrThrow",
-  "count",
-  "aggregate",
-  "groupBy",
-] as const;
-
-/**
- * Create a view delegate that wraps an existing model delegate.
- * Only read operations are exposed; writes are omitted.
- */
-export function createViewDelegate(params: {
-  delegate: Record<string, Function>;
-  modelMeta: ModelMeta;
-  viewFields: Record<string, true>;
-  viewDefinition: ViewDefinition;
-  allModelsMeta: ModelMetaMap;
-  modelSchema?: ValidationSchema;
-}): Record<string, Function> {
-  const { delegate, modelMeta, viewFields, viewDefinition, allModelsMeta, modelSchema } = params;
-
-  // Build the picked schema eagerly (once per view, not per query)
-  const viewSchema = modelSchema
-    ? buildPickedSchema({ schema: modelSchema, fields: viewFields })
-    : undefined;
-
-  const viewDelegate: Record<string, Function> = {};
-
-  // count, aggregate, groupBy — pass through unchanged
-  for (const op of ["count", "aggregate", "groupBy"] as const) {
-    if (typeof delegate[op] === "function") {
-      viewDelegate[op] = delegate[op]!.bind(delegate);
-    }
-  }
-
-  // Read operations that return model instances — wrap with view logic
-  for (const op of ["findMany", "findFirst", "findUnique", "findUniqueOrThrow", "findFirstOrThrow"] as const) {
-    const originalFn = delegate[op];
-    if (typeof originalFn !== "function") continue;
-
-    viewDelegate[op] = async function (args: Record<string, unknown> = {}): Promise<unknown> {
-      // Merge view fields + reveal into args
-      const { mergedArgs, revealedFields } = mergeViewArgs({
-        args,
-        viewFields,
-        viewDefinition,
-        modelMeta,
-        allModelsMeta,
-      });
-
-      // Call the original delegate method with merged args
-      const rawResult = await originalFn.call(delegate, mergedArgs);
-
-      // Handle null/undefined (findFirst, findUnique)
-      if (rawResult === null || rawResult === undefined) {
-        return rawResult;
-      }
-
-      // Build the query-specific schema (view fields + revealed fields)
-      let querySchema = viewSchema;
-      if (Object.keys(revealedFields).length > 0 && modelSchema) {
-        const allFields = { ...viewFields, ...revealedFields };
-        querySchema = buildPickedSchema({ schema: modelSchema, fields: allFields }) ?? viewSchema;
-      }
-
-      // Wrap results
-      if (Array.isArray(rawResult)) {
-        // Apply Zod safety net first
-        const filtered = applyViewSchemaFilter({
-          records: rawResult as Record<string, unknown>[],
-          viewSchema: querySchema,
-        });
-        return wrapResultsWithView({
-          records: filtered,
-          viewFields,
-          revealedFields,
-          viewDefinition,
-          modelMeta,
-          allModelsMeta,
-        });
-      } else {
-        // Single result (findUniqueOrThrow, findFirstOrThrow)
-        const filtered = applyViewSchemaFilter({
-          records: [rawResult as Record<string, unknown>],
-          viewSchema: querySchema,
-        });
-        const wrapped = wrapResultsWithView({
-          records: filtered,
-          viewFields,
-          revealedFields,
-          viewDefinition,
-          modelMeta,
-          allModelsMeta,
-        });
-        return wrapped[0] ?? null;
-      }
-    };
-  }
-
-  return viewDelegate;
-}
-
-// ─── View Client Creation ─────────────────────────────────────────
-
-/**
- * Create a view client from an existing client and a view definition.
- * Returns an object with only the models specified in the definition,
- * each with read-only delegates restricted to view fields.
- */
-export function createView(params: {
-  client: Record<string, unknown>;
-  name: string;
-  definition: ViewDefinition;
-  allModelsMeta: ModelMetaMap;
-  schemas?: Record<string, ModelSchemas>;
-}): Record<string, unknown> {
-  const { client, name, definition, allModelsMeta, schemas } = params;
-
-  const viewClient: Record<string, unknown> = {};
-
-  for (const [modelKey, viewFields] of Object.entries(definition)) {
-    const delegate = client[modelKey] as Record<string, Function> | undefined;
-    if (!delegate || typeof delegate !== "object") {
-      throw new Error(
-        `[vibeorm] View "${name}": model "${modelKey}" not found on the client. ` +
-        `Available models: ${Object.keys(allModelsMeta).join(", ")}`
-      );
-    }
-
-    const modelMeta = allModelsMeta[modelKey];
-    if (!modelMeta) {
-      throw new Error(
-        `[vibeorm] View "${name}": no metadata found for model "${modelKey}".`
-      );
-    }
-
-    viewClient[modelKey] = createViewDelegate({
-      delegate,
-      modelMeta,
-      viewFields,
-      viewDefinition: definition,
-      allModelsMeta,
-      modelSchema: schemas?.[modelKey]?.model,
-    });
-  }
-
-  return viewClient;
-}