@wix/sdk-types 1.12.8 → 1.13.0

package/build/index.d.mts

@@ -334,6 +334,65 @@ type Except<ObjectType, KeysType extends keyof ObjectType, Options extends Excep
 	? Partial<Record<KeysType, never>>
 	: {});
 
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see SimplifyDeep
+@category Object
+*/
+type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
+
 /**
 Returns a boolean for whether the given type is `never`.
 
@@ -535,4 +594,56 @@ type MaybeContext<T extends Descriptors> = globalThis.ContextualClient extends {
     host: Host;
 } ? BuildDescriptors<T, globalThis.ContextualClient['host']> : T;
 
-export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };
+/**
+ * Expose fields based on the current exposure toggle.
+ * @param T - The type to expose fields from.
+ * @param FieldsScope - A map of fields to their exposure scope, missing fields are considered public.
+ * @example Exposure toggle not set:
+ * ```ts
+ * type MyType = {
+ *  publicField: string;
+ *  alphaField: string;
+ * };
+ *
+ * type ExposedType = ExposeFieldsBasedOnToggle<MyType, { alphaField: 'alpha' }>;
+ * // ExposedType = { publicField: string; }
+ * ```
+ * @example Exposure toggle set to alpha:
+ * ```ts
+ * declare global {
+ *  interface SDKExposureToggle {
+ *   alpha: true;
+ *  }
+ * }
+ *
+ * type MyType = {
+ *  publicField: string;
+ *  alphaField: string;
+ * };
+ *
+ * type ExposedType = ExposeFieldsBasedOnToggle<MyType, { alphaField: 'alpha' }>;
+ * // ExposedType = { publicField: string; alphaField: string; }
+ */
+type ExposeFieldsBasedOnToggle<T extends Record<string, any>, FieldsScope extends Partial<Record<keyof T, Exposure>>> = Simplify<{
+    [K in keyof T as IsExposed<K, FieldsScope[K] extends Exposure ? FieldsScope[K] : 'public'>]: T[K];
+}>;
+declare global {
+    /**
+     * A global interface to set the exposure toggle for the SDK.
+     * @example
+     * ```ts
+     * declare global {
+     *  interface SDKExposureToggle {
+     *    alpha: true;
+     *  }
+     * }
+     */
+    interface SDKExposureToggle {
+    }
+}
+type Exposure = 'alpha' | 'public';
+type IsExposed<T, Scope extends Exposure> = Scope extends 'public' ? T : globalThis.SDKExposureToggle extends {
+    alpha: true;
+} ? T : never;
+
+export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };

package/build/index.d.ts

@@ -334,6 +334,65 @@ type Except<ObjectType, KeysType extends keyof ObjectType, Options extends Excep
 	? Partial<Record<KeysType, never>>
 	: {});
 
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see SimplifyDeep
+@category Object
+*/
+type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
+
 /**
 Returns a boolean for whether the given type is `never`.
 
@@ -535,4 +594,56 @@ type MaybeContext<T extends Descriptors> = globalThis.ContextualClient extends {
     host: Host;
 } ? BuildDescriptors<T, globalThis.ContextualClient['host']> : T;
 
-export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };
+/**
+ * Expose fields based on the current exposure toggle.
+ * @param T - The type to expose fields from.
+ * @param FieldsScope - A map of fields to their exposure scope, missing fields are considered public.
+ * @example Exposure toggle not set:
+ * ```ts
+ * type MyType = {
+ *  publicField: string;
+ *  alphaField: string;
+ * };
+ *
+ * type ExposedType = ExposeFieldsBasedOnToggle<MyType, { alphaField: 'alpha' }>;
+ * // ExposedType = { publicField: string; }
+ * ```
+ * @example Exposure toggle set to alpha:
+ * ```ts
+ * declare global {
+ *  interface SDKExposureToggle {
+ *   alpha: true;
+ *  }
+ * }
+ *
+ * type MyType = {
+ *  publicField: string;
+ *  alphaField: string;
+ * };
+ *
+ * type ExposedType = ExposeFieldsBasedOnToggle<MyType, { alphaField: 'alpha' }>;
+ * // ExposedType = { publicField: string; alphaField: string; }
+ */
+type ExposeFieldsBasedOnToggle<T extends Record<string, any>, FieldsScope extends Partial<Record<keyof T, Exposure>>> = Simplify<{
+    [K in keyof T as IsExposed<K, FieldsScope[K] extends Exposure ? FieldsScope[K] : 'public'>]: T[K];
+}>;
+declare global {
+    /**
+     * A global interface to set the exposure toggle for the SDK.
+     * @example
+     * ```ts
+     * declare global {
+     *  interface SDKExposureToggle {
+     *    alpha: true;
+     *  }
+     * }
+     */
+    interface SDKExposureToggle {
+    }
+}
+type Exposure = 'alpha' | 'public';
+type IsExposed<T, Scope extends Exposure> = Scope extends 'public' ? T : globalThis.SDKExposureToggle extends {
+    alpha: true;
+} ? T : never;
+
+export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/sdk-types",
-  "version": "1.12.8",
+  "version": "1.13.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Ronny Ringel",
@@ -58,5 +58,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "63b5f65cadbdc43d77cb40e3bcfb19670a4185b479de5316ea38bf58"
+  "falconPackageHash": "d5217e053bcbd31cbd1e1df8a6961bd38ab9ab0a5d54fd9ac456c89c"
 }