@proofkit/fmodata 0.1.0-alpha.9 → 0.1.0-beta.23

package/src/types.ts

@@ -1,18 +1,21 @@
-import { type FFetchOptions } from "@fetchkit/ffetch";
+import type { FFetchOptions } from "@fetchkit/ffetch";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { InternalLogger } from "./logger";
 
 export type Auth = { username: string; password: string } | { apiKey: string };
 
 export interface ExecutableBuilder<T> {
   execute(): Promise<Result<T>>;
+  // biome-ignore lint/suspicious/noExplicitAny: Request body can be any JSON-serializable value
   getRequestConfig(): { method: string; url: string; body?: any };
 
   /**
    * Convert this builder to a native Request object for batch processing.
    * @param baseUrl - The base URL for the OData service
+   * @param options - Optional execution options (e.g., includeODataAnnotations)
    * @returns A native Request object
    */
-  toRequest(baseUrl: string): Request;
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request;
 
   /**
    * Process a raw Response object into a typed Result.
@@ -21,29 +24,33 @@ export interface ExecutableBuilder<T> {
    * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)
    * @returns A typed Result with the builder's expected return type
    */
-  processResponse(
-    response: Response,
-    options?: ExecuteOptions,
-  ): Promise<Result<T>>;
+  processResponse(response: Response, options?: ExecuteOptions): Promise<Result<T>>;
 }
 
 export interface ExecutionContext {
   _makeRequest<T>(
     url: string,
-    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+    options?: RequestInit &
+      FFetchOptions & {
+        useEntityIds?: boolean;
+        includeSpecialColumns?: boolean;
+      },
   ): Promise<Result<T>>;
   _setUseEntityIds?(useEntityIds: boolean): void;
   _getUseEntityIds?(): boolean;
+  _setIncludeSpecialColumns?(includeSpecialColumns: boolean): void;
+  _getIncludeSpecialColumns?(): boolean;
   _getBaseUrl?(): string;
+  _getLogger?(): InternalLogger;
 }
 
 export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
-  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>
-    ? Output
-    : never;
+  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> ? Output : never;
 };
 
-export type WithSystemFields<T> =
+export type WithSpecialColumns<T> =
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
   T extends Record<string, any>
     ? T & {
         ROWID: number;
@@ -51,26 +58,21 @@ export type WithSystemFields<T> =
       }
     : never;
 
-// Helper type to exclude system fields from a union of keys
-export type ExcludeSystemFields<T extends keyof any> = Exclude<
-  T,
-  "ROWID" | "ROWMODID"
->;
-
-// Helper type to omit system fields from an object type
-export type OmitSystemFields<T> = Omit<T, "ROWID" | "ROWMODID">;
+// Helper type to exclude special columns from a union of keys
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any key type
+export type ExcludeSystemFields<T extends keyof any> = Exclude<T, "ROWID" | "ROWMODID">;
 
 // OData record metadata fields (present on each record)
-export type ODataRecordMetadata = {
+export interface ODataRecordMetadata {
   "@id": string;
   "@editLink": string;
-};
+}
 
 // OData response wrapper (top-level, internal use only)
-export type ODataListResponse<T> = {
+export interface ODataListResponse<T> {
   "@context": string;
   value: (T & ODataRecordMetadata)[];
-};
+}
 
 export type ODataSingleResponse<T> = T &
   ODataRecordMetadata & {
@@ -78,51 +80,62 @@ export type ODataSingleResponse<T> = T &
   };
 
 // OData response for single field values
-export type ODataFieldResponse<T> = {
+export interface ODataFieldResponse<T> {
   "@context": string;
   value: T;
-};
+}
 
 // Result pattern for execute responses
 export type Result<T, E = import("./errors").FMODataErrorType> =
   | { data: T; error: undefined }
   | { data: undefined; error: E };
 
+// Batch operation result types
+export interface BatchItemResult<T> {
+  data: T | undefined;
+  error: import("./errors").FMODataErrorType | undefined;
+  status: number; // HTTP status code (0 for truncated)
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any tuple type
+export interface BatchResult<T extends readonly any[]> {
+  results: { [K in keyof T]: BatchItemResult<T[K]> };
+  successCount: number;
+  errorCount: number;
+  truncated: boolean;
+  firstErrorIndex: number | null;
+}
+
 // Make specific keys required, rest optional
-export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &
-  Required<Pick<T, Keys>>;
+export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> & Required<Pick<T, Keys>>;
 
 // Extract keys from schema where validator doesn't allow null/undefined (auto-required fields)
-export type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> =
-  {
-    [K in keyof Schema]: Extract<
-      StandardSchemaV1.InferOutput<Schema[K]>,
-      null | undefined
-    > extends never
-      ? K
-      : never;
-  }[keyof Schema];
+export type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> = {
+  [K in keyof Schema]: Extract<StandardSchemaV1.InferOutput<Schema[K]>, null | undefined> extends never ? K : never;
+}[keyof Schema];
 
 // Helper type to compute excluded fields (readOnly fields + idField)
 export type ExcludedFields<
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any key type
   IdField extends keyof any | undefined,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any array type
   ReadOnly extends readonly any[],
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any key type
 > = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];
 
 // Helper type for InsertData computation
-type ComputeInsertData<
+type _ComputeInsertData<
   Schema extends Record<string, StandardSchemaV1>,
   IdField extends keyof Schema | undefined,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any array type
   Required extends readonly any[],
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any array type
   ReadOnly extends readonly any[],
 > = [Required[number]] extends [keyof InferSchemaType<Schema>]
   ? Required extends readonly (keyof InferSchemaType<Schema>)[]
     ? MakeFieldsRequired<
         Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,
-        Exclude<
-          AutoRequiredKeys<Schema> | Required[number],
-          ExcludedFields<IdField, ReadOnly>
-        >
+        Exclude<AutoRequiredKeys<Schema> | Required[number], ExcludedFields<IdField, ReadOnly>>
       >
     : MakeFieldsRequired<
         Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,
@@ -133,77 +146,59 @@ type ComputeInsertData<
       Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>
     >;
 
-// Extract insert data type from BaseTable
-// Auto-infers required fields from validator nullability + user-specified required fields
-// Excludes readOnly fields and idField
-export type InsertData<BT> = BT extends import("./client/base-table").BaseTable<
-  any,
-  any,
-  any,
-  any
->
-  ? BT extends {
-      schema: infer Schema;
-      idField?: infer IdField;
-      required?: infer Required;
-      readOnly?: infer ReadOnly;
-    }
-    ? Schema extends Record<string, StandardSchemaV1>
-      ? IdField extends keyof Schema | undefined
-        ? Required extends readonly any[]
-          ? ReadOnly extends readonly any[]
-            ? ComputeInsertData<
-                Schema,
-                Extract<IdField, keyof Schema | undefined>,
-                Required,
-                ReadOnly
-              >
-            : Partial<Record<string, any>>
-          : Partial<Record<string, any>>
-        : Partial<Record<string, any>>
-      : Partial<Record<string, any>>
-    : Partial<Record<string, any>>
-  : Partial<Record<string, any>>;
-
-// Extract update data type from BaseTable
-// All fields are optional for updates, excludes readOnly fields and idField
-export type UpdateData<BT> = BT extends import("./client/base-table").BaseTable<
-  any,
-  any,
-  any,
-  any
->
-  ? BT extends {
-      schema: infer Schema;
-      idField?: infer IdField;
-      readOnly?: infer ReadOnly;
-    }
-    ? Schema extends Record<string, StandardSchemaV1>
-      ? IdField extends keyof Schema | undefined
-        ? ReadOnly extends readonly any[]
-          ? Partial<
-              Omit<
-                InferSchemaType<Schema>,
-                ExcludedFields<
-                  Extract<IdField, keyof Schema | undefined>,
-                  ReadOnly
-                >
-              >
-            >
-          : Partial<Record<string, any>>
-        : Partial<Record<string, any>>
-      : Partial<Record<string, any>>
-    : Partial<Record<string, any>>
-  : Partial<Record<string, any>>;
-
-export type ExecuteOptions = {
+export interface ExecuteOptions {
   includeODataAnnotations?: boolean;
   skipValidation?: boolean;
   /**
    * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY
    */
   useEntityIds?: boolean;
-};
+  /**
+   * Overrides the default behavior of the database to include special columns (ROWID and ROWMODID) in THIS REQUEST ONLY.
+   * Note: Special columns are only included when there is no $select query.
+   */
+  includeSpecialColumns?: boolean;
+}
+
+/**
+ * Type for the fetchHandler callback function.
+ * This is a convenience type export that matches the fetchHandler signature in FFetchOptions.
+ *
+ * @example
+ * ```typescript
+ * import type { FetchHandler } from '@proofkit/fmodata';
+ *
+ * const myFetchHandler: FetchHandler = (input, init) => {
+ *   console.log('Custom fetch:', input);
+ *   return fetch(input, init);
+ * };
+ *
+ * await query.execute({
+ *   fetchHandler: myFetchHandler
+ * });
+ * ```
+ */
+export type FetchHandler = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Combined type for execute() method options.
+ *
+ * Uses FFetchOptions from @fetchkit/ffetch to ensure proper type inference.
+ * FFetchOptions is re-exported in the package to ensure type availability in consuming packages.
+ */
+export type ExecuteMethodOptions<EO extends ExecuteOptions = ExecuteOptions> = RequestInit &
+  FFetchOptions &
+  ExecuteOptions &
+  EO;
+
+/**
+ * Get the Accept header value based on includeODataAnnotations option
+ * @param includeODataAnnotations - Whether to include OData annotations
+ * @returns Accept header value
+ */
+export function getAcceptHeader(includeODataAnnotations?: boolean): string {
+  return includeODataAnnotations === true ? "application/json" : "application/json;odata.metadata=none";
+}
 
 export type ConditionallyWithODataAnnotations<
   T,
@@ -215,7 +210,53 @@ export type ConditionallyWithODataAnnotations<
     }
   : T;
 
-// Helper type to extract schema from a TableOccurrence
+/**
+ * Normalizes includeSpecialColumns with a database-level default.
+ * Uses distributive conditional types to handle unions correctly.
+ * @template IncludeSpecialColumns - The includeSpecialColumns value from execute options
+ * @template DatabaseDefault - The database-level includeSpecialColumns setting (defaults to false)
+ */
+export type NormalizeIncludeSpecialColumns<
+  IncludeSpecialColumns extends boolean | undefined,
+  DatabaseDefault extends boolean = false,
+> = [IncludeSpecialColumns] extends [true] ? true : [IncludeSpecialColumns] extends [false] ? false : DatabaseDefault; // When undefined, use database-level default
+
+/**
+ * Conditionally adds ROWID and ROWMODID special columns to a type.
+ * Special columns are only included when:
+ * - includeSpecialColumns is true AND
+ * - hasSelect is false (no $select query was applied) AND
+ * - T is an object type (not a primitive like string or number)
+ *
+ * Handles both single objects and arrays of objects.
+ */
+export type ConditionallyWithSpecialColumns<
+  T,
+  IncludeSpecialColumns extends boolean,
+  HasSelect extends boolean,
+> = IncludeSpecialColumns extends true
+  ? HasSelect extends false
+    ? // Handle array types
+      T extends readonly (infer U)[]
+      ? // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+        U extends Record<string, any>
+        ? (U & {
+            ROWID: number;
+            ROWMODID: number;
+          })[]
+        : T
+      : // Handle single object types
+        // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+        T extends Record<string, any>
+        ? T & {
+            ROWID: number;
+            ROWMODID: number;
+          }
+        : T // Don't add special columns to primitives (e.g., single field queries)
+    : T
+  : T;
+
+// Helper type to extract schema from a FMTable
 export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
   baseTable: { schema: infer S };
 }
@@ -224,14 +265,14 @@ export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
     : Record<string, StandardSchemaV1>
   : Record<string, StandardSchemaV1>;
 
-export type GenericFieldMetadata = {
+export interface GenericFieldMetadata {
   $Nullable?: boolean;
   "@Index"?: boolean;
   "@Calculation"?: boolean;
   "@Summary"?: boolean;
   "@Global"?: boolean;
   "@Org.OData.Core.V1.Permissions"?: "Org.OData.Core.V1.Permission@Read";
-};
+}
 
 export type StringFieldMetadata = GenericFieldMetadata & {
   $Type: "Edm.String";
@@ -260,13 +301,13 @@ export type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {
   "@VersionId"?: boolean;
 };
 
-export type StreamFieldMetadata = {
+export interface StreamFieldMetadata {
   $Type: "Edm.Stream";
   $Nullable?: boolean;
   "@EnclosedPath": string;
   "@ExternalOpenPath": string;
   "@ExternalSecurePath"?: string;
-};
+}
 
 export type FieldMetadata =
   | StringFieldMetadata
@@ -281,9 +322,9 @@ export type EntityType = {
   $Key: string[];
 } & Record<string, FieldMetadata>;
 
-export type EntitySet = {
+export interface EntitySet {
   $Kind: "EntitySet";
   $Type: string;
-};
+}
 
 export type Metadata = Record<string, EntityType | EntitySet>;