fraiseql 2.2.1 → 2.9.0

package/dist/index.d.mts

@@ -855,14 +855,8 @@ declare function Type(_config?: TypeConfig): <T extends {
 /**
  * Configuration for Query and Mutation decorators.
  */
-interface SqlSourceDispatchConfig {
-    argument: string;
-    mapping?: Record<string, string>;
-    template?: string;
-}
 interface OperationConfig {
     sqlSource?: string;
-    sqlSourceDispatch?: SqlSourceDispatchConfig;
     autoParams?: Record<string, boolean>;
     operation?: string;
     jsonbColumn?: string;
@@ -912,6 +906,42 @@ declare function Query(config?: OperationConfig): (_target: any, propertyKey: st
  */
 interface MutationConfig extends OperationConfig {
     operation?: "CREATE" | "UPDATE" | "DELETE" | "CUSTOM";
+    /**
+     * Whether a successful run of this mutation writes a Change-Spine change-log row.
+     *
+     * Defaults to `true`. Set `changelog: false` to opt this single mutation out of the
+     * in-transaction change-log outbox while the rest of the schema keeps logging.
+     * Omitting it leaves the key out of the JSON, and the compiler defaults it to `true`
+     * (a row is written only when the global `[changelog]` switch and this per-mutation
+     * flag are both on).
+     */
+    changelog?: boolean;
+    /**
+     * Whether a successful, state-changing run of this mutation also records the
+     * changed entity's pre-image (before-state) into the Change-Spine
+     * `object_data_before` column, alongside the after-state in `object_data` —
+     * sourced from an optional `entity_before` on the mutation's
+     * `app.mutation_response`.
+     *
+     * Defaults to `false`. Set `changelogPreImage: true` for audit-sensitive
+     * mutations that need an inline Debezium-style `{before, after}` on the single
+     * change event. Omitting it leaves the key out of the JSON, and the compiler
+     * defaults it to `false` (after-image only, today's behavior).
+     */
+    changelogPreImage?: boolean;
+    /**
+     * How the GraphQL `input` argument is passed to the SQL function:
+     * `"flatten"` (positional columns, the default) or `"jsonb"` (the whole input
+     * as one `jsonb` argument).
+     *
+     * Orthogonal to `operation`: set `inputStyle: "jsonb"` so a backend using the
+     * single-`jsonb`-wrapper convention (`fn(input_payload jsonb, …)`) can register
+     * the real DML verb (`CREATE`/`DELETE`/`CUSTOM`) instead of being forced to
+     * `UPDATE` purely to opt into single-JSONB input passing — the Change Spine then
+     * records the true `modification_type`. Omitting it leaves the key out of the
+     * JSON, and the compiler defaults it to `"flatten"`.
+     */
+    inputStyle?: "flatten" | "jsonb";
 }
 /**
  * Decorator to mark a function as a GraphQL mutation.
@@ -1114,46 +1144,34 @@ declare function registerTypeFields(typeName: string, fields: Field[], descripti
     crud?: boolean | string[];
     cascade?: boolean;
 }): void;
-/**
- * Config object form for registerQuery.
- */
-interface RegisterQueryConfig {
-    returnType: string;
-    returnsList?: boolean;
-    nullable?: boolean;
-    arguments?: ArgumentDefinition[];
-    description?: string;
-    sqlSource?: string;
-    sqlSourceDispatch?: {
-        argument: string;
-        mapping?: Record<string, string>;
-        template?: string;
-    };
-    [key: string]: unknown;
-}
 /**
  * Helper function to manually register query with full metadata.
  *
- * Accepts either the classic positional style:
- *   registerQuery(name, returnType, returnsList, nullable, args, description?, config?)
- *
- * Or a compact object style:
- *   registerQuery(name, { returnType, returnsList?, nullable?, arguments?, sqlSourceDispatch?, ... })
+ * @param name - Query name
+ * @param returnType - Return type name
+ * @param returnsList - Whether query returns a list
+ * @param nullable - Whether result can be null
+ * @param args - Argument definitions
+ * @param description - Optional query description
+ * @param config - Additional configuration
  *
  * @example
  * ```ts
- * registerQuery("orders", {
- *   returnType: "Order",
- *   returnsList: true,
- *   sqlSourceDispatch: {
- *     argument: "interval",
- *     mapping: { DAY: "tf_orders_day", WEEK: "tf_orders_week" },
- *   },
- *   arguments: [{ name: "interval", type: "TimeInterval", nullable: false }],
- * });
+ * registerQuery(
+ *   "users",
+ *   "User",
+ *   true,
+ *   false,
+ *   [
+ *     { name: "limit", type: "Int", nullable: false, default: 10 },
+ *     { name: "offset", type: "Int", nullable: false, default: 0 }
+ *   ],
+ *   "Get list of users",
+ *   { sql_source: "v_user" }
+ * );
  * ```
  */
-declare function registerQuery(name: string, returnTypeOrConfig: string | RegisterQueryConfig, returnsList?: boolean, nullable?: boolean, args?: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+declare function registerQuery(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
 /**
  * Helper function to manually register mutation with full metadata.
  *
@@ -1323,39 +1341,6 @@ declare function generateCrudOperations(typeName: string, fields: Field[], crud:
  * that can be consumed by the fraiseql-cli compiler.
  */
 
-/**
- * Configuration helper for queries and mutations.
- *
- * This function is called inside decorated functions to specify SQL mapping
- * and other configuration. The config is stored temporarily and applied by
- * the decorator.
- *
- * @param config - Configuration options:
- *   - sqlSource: SQL view name (queries) or function name (mutations)
- *   - operation: Mutation operation type (CREATE, UPDATE, DELETE, CUSTOM)
- *   - autoParams: Auto-parameter configuration (limit, offset, where, order_by)
- *   - jsonbColumn: JSONB column name for flexible schemas
- *
- * @example
- * ```ts
- * @Query()
- * function users(limit: number = 10) {
- *   return config({
- *     sqlSource: "v_user",
- *     autoParams: { limit: true, offset: true, where: true }
- *   });
- * }
- *
- * @Mutation()
- * function createUser(name: string, email: string) {
- *   return config({
- *     sqlSource: "fn_create_user",
- *     operation: "CREATE"
- *   });
- * }
- * ```
- */
-declare function config(configObj: Record<string, unknown>): void;
 /**
  * Export the schema registry to a JSON file.
  *
@@ -1702,6 +1687,6 @@ declare class FraiseQLClient {
  *
  * @packageDocumentation
  */
-declare const version = "2.0.0-alpha.1";
+declare const version = "2.9.0";
 
-export { type APIKey, type AirportCode, type ArgumentDefinition, type ArgumentInfo, AuthenticationError, type CIDR, type CUSIP, type Color, type ContainerNumber, type Coordinates, type CountryCode, type CurrencyCode, CustomScalar, DEFAULT_RETRY_CONFIG, type Date, type DateRange, type DateTime, type Decimal, type DomainName, type Duration, type Email, type EnumConfig, type EnumDefinition, type EnumValue, type ExchangeCode, type ExchangeRate, type Field, type FieldInfo, type FieldMetadata, type File, type FlightNumber, FraiseQLClient, type FraiseQLClientConfig, FraiseQLError, type FunctionSignature, GraphQLError, type GraphQLErrorEntry, type HTML, type HashSHA256, type Hostname, type HttpRetryConfig, type IBAN, type ID, type IPAddress, type IPv4, type IPv6, type ISIN, type Image, type InputConfig, type InputTypeDefinition, type InterfaceConfig, type InterfaceDefinition, type Json, type LEI, type LTree, type LanguageCode, type Latitude, type LicensePlate, type LocaleCode, type Longitude, type MACAddress, type MIC, type Markdown, type MimeType, type Money, Mutation, type MutationConfig, type MutationDefinition, NetworkError, Observer, type OperationConfig, type Percentage, type PhoneNumber, type Port, type PortCode, type PostalCode, Query, type QueryDefinition, RateLimitError, type RetryConfig, type ReturnTypeInfo, SCALAR_NAMES, type SEDOL, Scalar, ScalarValidationError, type Schema, SchemaRegistry, type SemanticVersion, type Slug, type StockSymbol, Subscription, type SubscriptionConfig, type SubscriptionDefinition, type Time, TimeoutError, type Timezone, type TrackingNumber, Type, type TypeConfig, type TypeDefinition, type URL, type UUID, type UnionConfig, type UnionDefinition, type VIN, type Vector, config, email, enum_, executeWithRetry, exportSchema, exportSchemaToString, exportTypes, extractFieldInfo, extractFunctionSignature, field, generateCrudOperations, getAllCustomScalars, getSchemaDict, input, interface_, isScalarType, registerMutation, registerQuery, registerSubscription, registerTypeFields, slack, typeToGraphQL, union, validateCustomScalar, version, webhook };
+export { type APIKey, type AirportCode, type ArgumentDefinition, type ArgumentInfo, AuthenticationError, type CIDR, type CUSIP, type Color, type ContainerNumber, type Coordinates, type CountryCode, type CurrencyCode, CustomScalar, DEFAULT_RETRY_CONFIG, type Date, type DateRange, type DateTime, type Decimal, type DomainName, type Duration, type Email, type EnumConfig, type EnumDefinition, type EnumValue, type ExchangeCode, type ExchangeRate, type Field, type FieldInfo, type FieldMetadata, type File, type FlightNumber, FraiseQLClient, type FraiseQLClientConfig, FraiseQLError, type FunctionSignature, GraphQLError, type GraphQLErrorEntry, type HTML, type HashSHA256, type Hostname, type HttpRetryConfig, type IBAN, type ID, type IPAddress, type IPv4, type IPv6, type ISIN, type Image, type InputConfig, type InputTypeDefinition, type InterfaceConfig, type InterfaceDefinition, type Json, type LEI, type LTree, type LanguageCode, type Latitude, type LicensePlate, type LocaleCode, type Longitude, type MACAddress, type MIC, type Markdown, type MimeType, type Money, Mutation, type MutationConfig, type MutationDefinition, NetworkError, Observer, type OperationConfig, type Percentage, type PhoneNumber, type Port, type PortCode, type PostalCode, Query, type QueryDefinition, RateLimitError, type RetryConfig, type ReturnTypeInfo, SCALAR_NAMES, type SEDOL, Scalar, ScalarValidationError, type Schema, SchemaRegistry, type SemanticVersion, type Slug, type StockSymbol, Subscription, type SubscriptionConfig, type SubscriptionDefinition, type Time, TimeoutError, type Timezone, type TrackingNumber, Type, type TypeConfig, type TypeDefinition, type URL, type UUID, type UnionConfig, type UnionDefinition, type VIN, type Vector, email, enum_, executeWithRetry, exportSchema, exportSchemaToString, exportTypes, extractFieldInfo, extractFunctionSignature, field, generateCrudOperations, getAllCustomScalars, getSchemaDict, input, interface_, isScalarType, registerMutation, registerQuery, registerSubscription, registerTypeFields, slack, typeToGraphQL, union, validateCustomScalar, version, webhook };

package/dist/index.d.ts

@@ -855,14 +855,8 @@ declare function Type(_config?: TypeConfig): <T extends {
 /**
  * Configuration for Query and Mutation decorators.
  */
-interface SqlSourceDispatchConfig {
-    argument: string;
-    mapping?: Record<string, string>;
-    template?: string;
-}
 interface OperationConfig {
     sqlSource?: string;
-    sqlSourceDispatch?: SqlSourceDispatchConfig;
     autoParams?: Record<string, boolean>;
     operation?: string;
     jsonbColumn?: string;
@@ -912,6 +906,42 @@ declare function Query(config?: OperationConfig): (_target: any, propertyKey: st
  */
 interface MutationConfig extends OperationConfig {
     operation?: "CREATE" | "UPDATE" | "DELETE" | "CUSTOM";
+    /**
+     * Whether a successful run of this mutation writes a Change-Spine change-log row.
+     *
+     * Defaults to `true`. Set `changelog: false` to opt this single mutation out of the
+     * in-transaction change-log outbox while the rest of the schema keeps logging.
+     * Omitting it leaves the key out of the JSON, and the compiler defaults it to `true`
+     * (a row is written only when the global `[changelog]` switch and this per-mutation
+     * flag are both on).
+     */
+    changelog?: boolean;
+    /**
+     * Whether a successful, state-changing run of this mutation also records the
+     * changed entity's pre-image (before-state) into the Change-Spine
+     * `object_data_before` column, alongside the after-state in `object_data` —
+     * sourced from an optional `entity_before` on the mutation's
+     * `app.mutation_response`.
+     *
+     * Defaults to `false`. Set `changelogPreImage: true` for audit-sensitive
+     * mutations that need an inline Debezium-style `{before, after}` on the single
+     * change event. Omitting it leaves the key out of the JSON, and the compiler
+     * defaults it to `false` (after-image only, today's behavior).
+     */
+    changelogPreImage?: boolean;
+    /**
+     * How the GraphQL `input` argument is passed to the SQL function:
+     * `"flatten"` (positional columns, the default) or `"jsonb"` (the whole input
+     * as one `jsonb` argument).
+     *
+     * Orthogonal to `operation`: set `inputStyle: "jsonb"` so a backend using the
+     * single-`jsonb`-wrapper convention (`fn(input_payload jsonb, …)`) can register
+     * the real DML verb (`CREATE`/`DELETE`/`CUSTOM`) instead of being forced to
+     * `UPDATE` purely to opt into single-JSONB input passing — the Change Spine then
+     * records the true `modification_type`. Omitting it leaves the key out of the
+     * JSON, and the compiler defaults it to `"flatten"`.
+     */
+    inputStyle?: "flatten" | "jsonb";
 }
 /**
  * Decorator to mark a function as a GraphQL mutation.
@@ -1114,46 +1144,34 @@ declare function registerTypeFields(typeName: string, fields: Field[], descripti
     crud?: boolean | string[];
     cascade?: boolean;
 }): void;
-/**
- * Config object form for registerQuery.
- */
-interface RegisterQueryConfig {
-    returnType: string;
-    returnsList?: boolean;
-    nullable?: boolean;
-    arguments?: ArgumentDefinition[];
-    description?: string;
-    sqlSource?: string;
-    sqlSourceDispatch?: {
-        argument: string;
-        mapping?: Record<string, string>;
-        template?: string;
-    };
-    [key: string]: unknown;
-}
 /**
  * Helper function to manually register query with full metadata.
  *
- * Accepts either the classic positional style:
- *   registerQuery(name, returnType, returnsList, nullable, args, description?, config?)
- *
- * Or a compact object style:
- *   registerQuery(name, { returnType, returnsList?, nullable?, arguments?, sqlSourceDispatch?, ... })
+ * @param name - Query name
+ * @param returnType - Return type name
+ * @param returnsList - Whether query returns a list
+ * @param nullable - Whether result can be null
+ * @param args - Argument definitions
+ * @param description - Optional query description
+ * @param config - Additional configuration
  *
  * @example
  * ```ts
- * registerQuery("orders", {
- *   returnType: "Order",
- *   returnsList: true,
- *   sqlSourceDispatch: {
- *     argument: "interval",
- *     mapping: { DAY: "tf_orders_day", WEEK: "tf_orders_week" },
- *   },
- *   arguments: [{ name: "interval", type: "TimeInterval", nullable: false }],
- * });
+ * registerQuery(
+ *   "users",
+ *   "User",
+ *   true,
+ *   false,
+ *   [
+ *     { name: "limit", type: "Int", nullable: false, default: 10 },
+ *     { name: "offset", type: "Int", nullable: false, default: 0 }
+ *   ],
+ *   "Get list of users",
+ *   { sql_source: "v_user" }
+ * );
  * ```
  */
-declare function registerQuery(name: string, returnTypeOrConfig: string | RegisterQueryConfig, returnsList?: boolean, nullable?: boolean, args?: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+declare function registerQuery(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
 /**
  * Helper function to manually register mutation with full metadata.
  *
@@ -1323,39 +1341,6 @@ declare function generateCrudOperations(typeName: string, fields: Field[], crud:
  * that can be consumed by the fraiseql-cli compiler.
  */
 
-/**
- * Configuration helper for queries and mutations.
- *
- * This function is called inside decorated functions to specify SQL mapping
- * and other configuration. The config is stored temporarily and applied by
- * the decorator.
- *
- * @param config - Configuration options:
- *   - sqlSource: SQL view name (queries) or function name (mutations)
- *   - operation: Mutation operation type (CREATE, UPDATE, DELETE, CUSTOM)
- *   - autoParams: Auto-parameter configuration (limit, offset, where, order_by)
- *   - jsonbColumn: JSONB column name for flexible schemas
- *
- * @example
- * ```ts
- * @Query()
- * function users(limit: number = 10) {
- *   return config({
- *     sqlSource: "v_user",
- *     autoParams: { limit: true, offset: true, where: true }
- *   });
- * }
- *
- * @Mutation()
- * function createUser(name: string, email: string) {
- *   return config({
- *     sqlSource: "fn_create_user",
- *     operation: "CREATE"
- *   });
- * }
- * ```
- */
-declare function config(configObj: Record<string, unknown>): void;
 /**
  * Export the schema registry to a JSON file.
  *
@@ -1702,6 +1687,6 @@ declare class FraiseQLClient {
  *
  * @packageDocumentation
  */
-declare const version = "2.0.0-alpha.1";
+declare const version = "2.9.0";
 
-export { type APIKey, type AirportCode, type ArgumentDefinition, type ArgumentInfo, AuthenticationError, type CIDR, type CUSIP, type Color, type ContainerNumber, type Coordinates, type CountryCode, type CurrencyCode, CustomScalar, DEFAULT_RETRY_CONFIG, type Date, type DateRange, type DateTime, type Decimal, type DomainName, type Duration, type Email, type EnumConfig, type EnumDefinition, type EnumValue, type ExchangeCode, type ExchangeRate, type Field, type FieldInfo, type FieldMetadata, type File, type FlightNumber, FraiseQLClient, type FraiseQLClientConfig, FraiseQLError, type FunctionSignature, GraphQLError, type GraphQLErrorEntry, type HTML, type HashSHA256, type Hostname, type HttpRetryConfig, type IBAN, type ID, type IPAddress, type IPv4, type IPv6, type ISIN, type Image, type InputConfig, type InputTypeDefinition, type InterfaceConfig, type InterfaceDefinition, type Json, type LEI, type LTree, type LanguageCode, type Latitude, type LicensePlate, type LocaleCode, type Longitude, type MACAddress, type MIC, type Markdown, type MimeType, type Money, Mutation, type MutationConfig, type MutationDefinition, NetworkError, Observer, type OperationConfig, type Percentage, type PhoneNumber, type Port, type PortCode, type PostalCode, Query, type QueryDefinition, RateLimitError, type RetryConfig, type ReturnTypeInfo, SCALAR_NAMES, type SEDOL, Scalar, ScalarValidationError, type Schema, SchemaRegistry, type SemanticVersion, type Slug, type StockSymbol, Subscription, type SubscriptionConfig, type SubscriptionDefinition, type Time, TimeoutError, type Timezone, type TrackingNumber, Type, type TypeConfig, type TypeDefinition, type URL, type UUID, type UnionConfig, type UnionDefinition, type VIN, type Vector, config, email, enum_, executeWithRetry, exportSchema, exportSchemaToString, exportTypes, extractFieldInfo, extractFunctionSignature, field, generateCrudOperations, getAllCustomScalars, getSchemaDict, input, interface_, isScalarType, registerMutation, registerQuery, registerSubscription, registerTypeFields, slack, typeToGraphQL, union, validateCustomScalar, version, webhook };
+export { type APIKey, type AirportCode, type ArgumentDefinition, type ArgumentInfo, AuthenticationError, type CIDR, type CUSIP, type Color, type ContainerNumber, type Coordinates, type CountryCode, type CurrencyCode, CustomScalar, DEFAULT_RETRY_CONFIG, type Date, type DateRange, type DateTime, type Decimal, type DomainName, type Duration, type Email, type EnumConfig, type EnumDefinition, type EnumValue, type ExchangeCode, type ExchangeRate, type Field, type FieldInfo, type FieldMetadata, type File, type FlightNumber, FraiseQLClient, type FraiseQLClientConfig, FraiseQLError, type FunctionSignature, GraphQLError, type GraphQLErrorEntry, type HTML, type HashSHA256, type Hostname, type HttpRetryConfig, type IBAN, type ID, type IPAddress, type IPv4, type IPv6, type ISIN, type Image, type InputConfig, type InputTypeDefinition, type InterfaceConfig, type InterfaceDefinition, type Json, type LEI, type LTree, type LanguageCode, type Latitude, type LicensePlate, type LocaleCode, type Longitude, type MACAddress, type MIC, type Markdown, type MimeType, type Money, Mutation, type MutationConfig, type MutationDefinition, NetworkError, Observer, type OperationConfig, type Percentage, type PhoneNumber, type Port, type PortCode, type PostalCode, Query, type QueryDefinition, RateLimitError, type RetryConfig, type ReturnTypeInfo, SCALAR_NAMES, type SEDOL, Scalar, ScalarValidationError, type Schema, SchemaRegistry, type SemanticVersion, type Slug, type StockSymbol, Subscription, type SubscriptionConfig, type SubscriptionDefinition, type Time, TimeoutError, type Timezone, type TrackingNumber, Type, type TypeConfig, type TypeDefinition, type URL, type UUID, type UnionConfig, type UnionDefinition, type VIN, type Vector, email, enum_, executeWithRetry, exportSchema, exportSchemaToString, exportTypes, extractFieldInfo, extractFunctionSignature, field, generateCrudOperations, getAllCustomScalars, getSchemaDict, input, interface_, isScalarType, registerMutation, registerQuery, registerSubscription, registerTypeFields, slack, typeToGraphQL, union, validateCustomScalar, version, webhook };