@empathyco/x-adapter 8.0.0-alpha.17 → 8.0.0-alpha.19

package/README.md

@@ -74,7 +74,7 @@ passed.
 ###### Types definition
 
 ```ts
-// API data models
+// API models
 interface ApiRequest {
   q?: string;
   id?: number;
@@ -89,7 +89,7 @@ interface ApiProduct {
   price: number;
 }
 
-// App's data models
+// App models
 interface AppSearchRequest {
   query: string;
 }
@@ -243,7 +243,7 @@ the value somehow.
 ###### Types definition
 
 ```ts
-// API data models
+// API models
 interface ApiUserRequest {
   q: string;
 }
@@ -256,7 +256,7 @@ interface ApiUser {
   firstName: string;
 }
 
-// App's data models
+// App models
 interface AppUserRequest {
   query: string;
 }
@@ -307,7 +307,7 @@ them you just have to provide with the `Path` of the data to map, and the `Schem
 ###### Types definition
 
 ```ts
-// API data models
+// API models
 interface ApiRequest {
   q: string;
 }
@@ -328,7 +328,7 @@ interface ApiAddress {
   postalCode: string;
 }
 
-// APP data models
+// App models
 interface AppRequest {
   query: string;
 }
@@ -408,34 +408,262 @@ export const searchUsersWithContactInfo = endpointAdapterFactory({
 
 #### Using a mutable schema
 
-This feature lets you have some default mappers, and modify or extend them for some concrete
-implementations. To do so, you should use the `createMutableSchema` helper function, and pass as a
-parameter the schema you want to make mutable.
+This feature lets you have some default schemas, and modify or extend them for some concrete
+implementations. To do so, you can use the `createMutableSchema` function, passing a `Source` and
+`Target` type parameters to map your models. This function will return a `MutableSchema` that apart
+from the mapping information will also contain some methods to create new schemas or modify the
+current one.
+
+In the example below we will create a `MutableSchema` to have a default object that will be reused
+for different endpoint calls.
+
+###### Types definition and MutableSchema
+
+```ts
+// API models
+export interface ApiBaseObject {
+  id: number;
+  body: string;
+}
+
+// APP models
+export interface AppBaseObject {
+  id: string;
+  text: string;
+}
+
+// Mutable Schema
+export const baseObjectSchema = createMutableSchema<ApiBaseObject, AppBaseObject>({
+  id: ({ id }) => id.toString(),
+  text: 'body'
+});
+```
+
+Once we have the `MutableSchema`, we can use the following methods to fit our different APIs needs:
+
+- `$extends`: Creates a new `MutableSchema` based on the original one. The original remains
+  unchanged. This can be useful if we need to create a new `EndpointAdapter` with models based on
+  another API.
+- `$override`: Merges/modifies the original `MutableSchema` partially, so the change will affect to
+  all the `EndpointAdapter`(s) that are using it. It can be used to change the structure of our
+  request/response mappers, or to add them new fields. Useful for clients with few differences in
+  their APIs. For example, you can create a library with a default adapter and use this library from
+  the customer projects overriding only the needed field (e.g. retrieve the images from `pictures`
+  instead of `images` in a products API).
+- `$replace`: Replaces completely the original `MutableSchema` by a new one, it won't exist anymore.
+  The change will affect to all the `EndpointAdapter`(s) that were using it. Useful for clients with
+  a completely different API/response to the standard you have been working with.
+
+###### Extend a MutableSchema to reuse it in two different endpoints with more fields
+
+```ts
+import { ApiBaseObject, AppBaseObject, baseObjectSchema } from '@/base-types';
+
+// Api models
+interface ApiPost extends ApiBaseObject {
+  title: string;
+}
+interface ApiPostsResponse {
+  posts: ApiPost[];
+}
+
+interface ApiComment extends ApiBaseObject {
+  postId: number;
+}
+interface ApiCommentsResponse {
+  comments: ApiComment[];
+}
+
+// App models
+interface AppPost extends AppBaseObject {
+  postTitle: string;
+}
+interface AppPostsResponse {
+  posts: AppPost[];
+}
+
+interface AppComment extends AppBaseObject {
+  postId: number;
+}
+interface AppCommentsResponse {
+  comments: AppComment[];
+}
+
+// Extend for posts endpoint
+const postSchema = baseObjectSchema.$extends<ApiPost, AppPost>({
+  postTitle: 'title'
+});
+
+const postsResponse = schemaMapperFactory<ApiPostsResponse, AppPostsResponse>({
+  posts: {
+    $subSchema: postSchema,
+    $path: 'posts'
+  }
+});
+
+export const searchPosts = endpointAdapterFactory({
+  endpoint: 'https://dummyjson.com/posts',
+  responseMapper: postsResponse
+});
+
+// Extend for comments endpoint
+const commentSchema = baseObjectSchema.$extends<ApiComment, AppComment>({
+  postId: 'postId'
+});
+
+const commentsResponse = schemaMapperFactory<ApiCommentsResponse, AppCommentsResponse>({
+  comments: {
+    $subSchema: commentSchema,
+    $path: 'comments'
+  }
+});
+
+export const searchComments = endpointAdapterFactory({
+  endpoint: 'https://dummyjson.com/comments',
+  responseMapper: commentsResponse
+});
+```
+
+###### Override a MutableSchema to add more fields
+
+As said above, the suitable context for using the `override` method would be a project with an API
+that doesn't differ too much against the one used in our "base project". That means we can reuse
+most of the types and schemas definitions, so we would only add a few new fields from the new API.
 
 ```ts
-// TODO: Creating a mutable schema
+import { ApiBaseObject, AppBaseObject, baseObjectSchema } from '@/base-types';
+
+// Api models
+interface ApiTodo {
+  completed: boolean;
+  todo: string;
+  userId: number;
+}
+
+interface ApiTodosResponse {
+  todos: ApiBaseObject[];
+}
+
+// App models
+interface AppTodo {
+  completed: boolean;
+  text: string;
+  userId: string;
+}
+
+interface AppTodosResponse {
+  todos: AppBaseObject[];
+}
+
+// Response mapper
+const todosResponse = schemaMapperFactory<ApiTodosResponse, AppTodosResponse>({
+  todos: {
+    $subSchema: baseObjectSchema,
+    $path: 'todos'
+  }
+});
+
+// Endpoint Adapter
+export const searchTodos = endpointAdapterFactory({
+  endpoint: 'https://dummyjson.com/todos',
+  responseMapper: todosResponse
+});
+
+// Override the original Schema. The Schema changes to map: 'id', 'completed', 'text' and 'userId''
+baseObjectSchema.$override<ApiTodo, AppTodo>({
+  completed: 'completed',
+  text: 'todo',
+  userId: ({ userId }) => userId.toString()
+});
 ```
 
-Once you have your mutable schema, you can use its available methods to obtain a new schema based on
-it:
+###### Replace a MutableSchema to completely change it
 
-- `replace`: Replaces completely the original Schema.
-- `override`: Merges the original schema with the new one.
-- `extends`: Creates a new Schema based on the original one. The original remains unchanged.
+In this case we are facing too many differences between API responses. We don't need to write a
+whole adapter from scratch, as there are other parts of the API that aren't changing so much, but we
+should replace some `endpointAdapter`'s schemas.
 
 ```ts
-// TODO: Mutable schema's methods: '$replace', '$override', '$extends'
+import { ApiBaseObject, AppBaseObject, baseObjectSchema } from '@/base-types';
+
+// Api models
+interface ApiQuote {
+  id: number;
+  quote: string;
+  author: string;
+}
+
+interface ApiQuotesResponse {
+  quotes: ApiBaseObject[];
+}
+
+// App models
+interface AppQuote {
+  quoteId: string;
+  quote: string;
+  author: string;
+}
+
+interface AppQuotesResponse {
+  quotes: AppBaseObject[];
+}
+
+// Response mapper
+const quotesResponse = schemaMapperFactory<ApiQuotesResponse, AppQuotesResponse>({
+  quotes: {
+    $subSchema: baseObjectSchema,
+    $path: 'quotes'
+  }
+});
+
+// Endpoint Adapter
+export const searchQuotes = endpointAdapterFactory({
+  endpoint: 'https://dummyjson.com/quotes',
+  responseMapper: quotesResponse
+});
+
+// Replace the original Schema
+baseObjectSchema.$replace<ApiQuote, AppQuote>({
+  quoteId: ({ id }) => id.toString(),
+  quote: 'quote',
+  author: 'author'
+});
 ```
 
 <br>
 
 ### Extend an adapter that uses schemas
 
-You can check the
-[x-platform-adapter](https://github.com/empathyco/x/tree/main/packages/x-adapter-platform) library.
-You will find a sample implementation of the `x-adapter` library based on the
-[Search Platform API](https://docs.empathy.co/develop-empathy-platform/api-reference/search-api.html),
-and also some guidance on how to extend it for your needs.
+Imagine you have a new setup and that you can reuse most of the stuff you have developed. Probably
+you have built an adapter instance as a configuration object that contains all of your
+`EndpointAdapter` calls, so you only need to extend the endpoint you need to change.
+
+```ts
+export const adapter = {
+  searchItem: getItemById,
+  searchList: searchComments
+  // Any endpoint adapter you are using to communicate with your API
+};
+
+adapter.searchList = searchComments.extends({
+  endpoint: 'https://dummyjson.com/comments/',
+  defaultRequestOptions: {
+    // If you need to send an id, a header...
+  },
+  defaultRequestOptions: {
+    parameters: {
+      limit: 10,
+      skip: 10
+    }
+  }
+});
+```
+
+For further detail, you can check the
+[x-platform-adapter](https://github.com/empathyco/x/tree/main/packages/x-adapter-platform) package.
+It is a whole adapter implementation using this `x-adapter` library to suit the
+[Search Platform API](https://docs.empathy.co/develop-empathy-platform/api-reference/search-api.html)
+needs.
 
 ## Test
 
@@ -452,9 +680,9 @@ npm test
 
 ## Contributing
 
-To start contributing to the project, please take a look to
-our **[Contributing Guide](https://github.com/empathyco/x/blob/main/.github/CONTRIBUTING.md).** Take
-in account that `x-adapter` is developed using [Typescript](https://www.typescriptlang.org/), so we
+To start contributing to the project, please take a look to our
+**[Contributing Guide](https://github.com/empathyco/x/blob/main/.github/CONTRIBUTING.md).** Take in
+account that `x-adapter` is developed using [Typescript](https://www.typescriptlang.org/), so we
 recommend you check it out.
 
 ## License

package/dist/cjs/schemas/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/schemas/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  AnyFunction,\n  DeepPartial,\n  ExtractPath,\n  ExtractPathByType,\n  ExtractType,\n  Primitive\n} from '@empathyco/x-utils';\nimport { MapperContext } from '../mappers/types';\n\n// TODO: EX-5830 - Enhance Schema type to support optional properties in the Source object\n/**\n * Template object to transform a source object to a target object.\n *\n * @remarks The source object must not have optional properties, as it could cause infinite\n * type instantiations.\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     price: {\n *       max: number;\n *       min: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     maxPrice: number;\n *     minPrice: number;\n *     img: string[]\n *   }\n *\n *   const schema: Schema<Source, Target> = {\n *     identifier: 'id',\n *     maxPrice: 'price.max',\n *     minPrice: ({ price }) => Math.min(0, price.min),\n *     img: 'images'\n *   };\n * ```\n * @public\n */\nexport type Schema<Source = any, Target = any> = {\n  [TargetKey in keyof Target]: SchemaTransformer<Source, Target, TargetKey>;\n};\n\n/**\n * A {@link Schema | schema} with extended functionality to: completely replace\n * the original schema, partially override it or create a new one.\n *\n * @param OriginalSchema - The {@link Schema | schema} that will be mutable.\n * @public\n */\nexport type MutableSchema<Source, Target> = Schema<Source, Target> & {\n  /**\n   * Replaces all usages of the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use instead of the original one.\n   * @returns The new {@link Schema | schema} that will be used.\n   */\n  $replace<NewSource, NewTarget>(\n    newSchema: Schema<NewSource, NewTarget>\n  ): MutableSchema<NewSource, NewTarget>;\n  /**\n   * Merges the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use to merge with the original one.\n   * @returns The {@link Schema | schema} returned by the merge.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $override<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Creates a new {@link Schema | schema} using the original one as starting point.\n   * The original {@link Schema | schema} will remain unchanged.\n   *\n   * @param newSchema - The {@link Schema | schema} to be used to extend the original one.\n   * @returns The {@link Schema | schema} created.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $extends<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Returns a string representing of the {@link Schema | schema}.\n   *\n   * @param includeInternalMethods - Flag to include in the string representation\n   * the internal methods. Disabled by default.\n   * @returns The string representation.\n   */\n  toString(includeInternalMethods?: boolean): string;\n};\n/**\n * The possible transformers to apply to the target key.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param TargetKey - The target key to apply the transformation.\n * @public\n */\nexport type SchemaTransformer<Source, Target, TargetKey extends keyof Target> =\n  | PathTransformer<Source, Target[TargetKey]>\n  | FunctionTransformer<Source, Target[TargetKey]>\n  | SubSchemaTransformer<Source, Target[TargetKey]>\n  | Schema<Source, Exclude<Target[TargetKey], AnyFunction | Primitive>>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: 'id',\n *     hits: 'count'\n *   };\n *\n *   const wrongSubSchema: Schema<Source, Target> = {\n *     // @ts-expect-error\n *     title: 'count', // This raises a TS error\n *     hits: 'count'\n *   };\n * ```\n * @public\n */\nexport type PathTransformer<Source, Target> = ExtractPathByType<Source, Target>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: source => source.id,\n *     hits: (source, context) => context.requestParameters.query === 'example'\n *      ? source.count\n *      : 0\n *   };\n * ```\n * @public\n */\nexport type FunctionTransformer<Source, Target> = (\n  source: Source,\n  context?: MapperContext\n) => Target;\n\n/**\n * An object containing a schema narrowing its source object based on the given path.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     facets: {\n *       name: string;\n *       count: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     filters: {\n *       id: string;\n *       numFound: number;\n *     };\n *     img: string[]\n *   }\n *\n *   const subSchema: SubSchemaTransformer<Source, Target['filters']> = {\n *     $path: 'facets',\n *     $subSchema: {\n *       id: 'name',\n *       numFound: 'count'\n *     }\n *   };\n * ```\n * @public\n */\nexport type SubSchemaTransformer<Source, Target> = {\n  [Path in ExtractPath<Source>]: {\n    $context?: MapperContext;\n    $path: Path;\n    $subSchema:\n      | SubSchema<Source, Target, Path>\n      | '$self'\n      | ((source: Source) => SubSchema<Source, Target, Path>);\n  };\n}[ExtractPath<Source>];\n\n/**\n * A {@link Schema | schema} that will be applied to an inner path of an object.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param Path - The path where the schema will be applied.\n * @public\n */\nexport type SubSchema<Source, Target, Path extends ExtractPath<Source>> = ExtractType<\n  Source,\n  Path\n> extends (infer SourceArrayType)[]\n  ? Target extends (infer TargetArrayType)[]\n    ? Schema<SourceArrayType, TargetArrayType>\n    : never\n  : Target extends []\n  ? never\n  : Schema<ExtractType<Source, Path>, Target>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/schemas/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  AnyFunction,\n  DeepPartial,\n  ExtractPath,\n  ExtractPathByType,\n  ExtractType,\n  Primitive\n} from '@empathyco/x-utils';\nimport { MapperContext } from '../mappers/types';\n\n// TODO: EX-5830 - Enhance Schema type to support optional properties in the Source object\n/**\n * Template object to transform a source object to a target object.\n *\n * @remarks The source object must not have optional properties, as it could cause infinite\n * type instantiations.\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     price: {\n *       max: number;\n *       min: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     maxPrice: number;\n *     minPrice: number;\n *     img: string[]\n *   }\n *\n *   const schema: Schema<Source, Target> = {\n *     identifier: 'id',\n *     maxPrice: 'price.max',\n *     minPrice: ({ price }) => Math.min(0, price.min),\n *     img: 'images'\n *   };\n * ```\n * @public\n */\nexport type Schema<Source = any, Target = any> = {\n  [TargetKey in keyof Target]: SchemaTransformer<Source, Target, TargetKey>;\n};\n\n/**\n * A {@link Schema | schema} with extended functionality to: completely replace\n * the original schema, partially override it or create a new one.\n *\n * @param OriginalSchema - The {@link Schema | schema} that will be mutable.\n * @public\n */\nexport type MutableSchema<Source, Target> = Schema<Source, Target> & {\n  /**\n   * Replaces all usages of the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use instead of the original one.\n   * @returns The new {@link Schema | schema} that will be used.\n   */\n  $replace<NewSource, NewTarget>(\n    newSchema: Schema<NewSource, NewTarget>\n  ): MutableSchema<NewSource, NewTarget>;\n  /**\n   * Merges the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use to merge with the original one.\n   * @returns The {@link Schema | schema} returned by the merge.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $override<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Creates a new {@link Schema | schema} using the original one as starting point.\n   * The original {@link Schema | schema} will remain unchanged.\n   *\n   * @param newSchema - The {@link Schema | schema} to be used to extend the original one.\n   * Both schema's Target and Source can be unique or also be extending from another one.\n   * @returns The {@link Schema | schema} created.\n   */\n  $extends<NewSource extends Source, NewTarget extends Target>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, Omit<NewTarget, keyof Target>>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $extends<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Returns a string representing of the {@link Schema | schema}.\n   *\n   * @param includeInternalMethods - Flag to include in the string representation\n   * the internal methods. Disabled by default.\n   * @returns The string representation.\n   */\n  toString(includeInternalMethods?: boolean): string;\n};\n/**\n * The possible transformers to apply to the target key.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param TargetKey - The target key to apply the transformation.\n * @public\n */\nexport type SchemaTransformer<Source, Target, TargetKey extends keyof Target> =\n  | PathTransformer<Source, Target[TargetKey]>\n  | FunctionTransformer<Source, Target[TargetKey]>\n  | SubSchemaTransformer<Source, Target[TargetKey]>\n  | Schema<Source, Exclude<Target[TargetKey], AnyFunction | Primitive>>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: 'id',\n *     hits: 'count'\n *   };\n *\n *   const wrongSubSchema: Schema<Source, Target> = {\n *     // @ts-expect-error\n *     title: 'count', // This raises a TS error\n *     hits: 'count'\n *   };\n * ```\n * @public\n */\nexport type PathTransformer<Source, Target> = ExtractPathByType<Source, Target>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: source => source.id,\n *     hits: (source, context) => context.requestParameters.query === 'example'\n *      ? source.count\n *      : 0\n *   };\n * ```\n * @public\n */\nexport type FunctionTransformer<Source, Target> = (\n  source: Source,\n  context?: MapperContext\n) => Target;\n\n/**\n * An object containing a schema narrowing its source object based on the given path.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     facets: {\n *       name: string;\n *       count: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     filters: {\n *       id: string;\n *       numFound: number;\n *     };\n *     img: string[]\n *   }\n *\n *   const subSchema: SubSchemaTransformer<Source, Target['filters']> = {\n *     $path: 'facets',\n *     $subSchema: {\n *       id: 'name',\n *       numFound: 'count'\n *     }\n *   };\n * ```\n * @public\n */\nexport type SubSchemaTransformer<Source, Target> = {\n  [Path in ExtractPath<Source>]: {\n    $context?: MapperContext;\n    $path: Path;\n    $subSchema:\n      | SubSchema<Source, Target, Path>\n      | '$self'\n      | ((source: Source) => SubSchema<Source, Target, Path>);\n  };\n}[ExtractPath<Source>];\n\n/**\n * A {@link Schema | schema} that will be applied to an inner path of an object.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param Path - The path where the schema will be applied.\n * @public\n */\nexport type SubSchema<Source, Target, Path extends ExtractPath<Source>> = ExtractType<\n  Source,\n  Path\n> extends (infer SourceArrayType)[]\n  ? Target extends (infer TargetArrayType)[]\n    ? Schema<SourceArrayType, TargetArrayType>\n    : never\n  : Target extends []\n  ? never\n  : Schema<ExtractType<Source, Path>, Target>;\n"]}

package/dist/cjs/schemas/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/schemas/utils.ts"],"names":[],"mappings":";;;AAAA,0DAAoD;AACpD,gDAAmE;AAGnE;;GAEG;AACH,MAAM,6BAA6B,GAAa,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,MAA8B;IAE9B,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,CAAC,SAAS;YAChB,IAAA,iBAAO,EAAC,IAAI,EAAE,GAAG,CAAC,EAAE;gBAClB,IAAI,gBAAgB,CAAC,GAAa,CAAC,EAAE;oBACnC,OAAO;iBACR;gBACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/B;+EACmE;YACnE,OAAO,IAAW,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,SAAS;YACjB,OAAO,IAAA,wBAAS,EAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;QACD,QAAQ,CAAC,SAAS;YAChB,OAAO,IAAA,wBAAS,EAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;QACD,QAAQ,CAAC,sBAAsB,GAAG,KAAK;YACrC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AA3BD,kDA2BC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,OAAO,6BAA6B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAFD,4CAEC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,IAA6B,EAC7B,sBAA+B,EAC/B,IAAI,GAAG,CAAC;IAER,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAA,iBAAO,EAAC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,IAAA,kBAAQ,EAAC,KAAK,CAAC,EAAE;YACnB,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,QAAQ,SAAS,CAC7C,KAAK,EACL,sBAAsB,EACtB,EAAE,IAAI,CACP,GAAG,WAAW,MAAM,CAAC;SACvB;aAAM,IAAI,CAAC,IAAA,oBAAU,EAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,sBAAsB,EAAE;YACjF,4EAA4E;YAC5E,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,KAAK,KAAK,KAAK,CAAC;SAC/C;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { deepMerge } from '@empathyco/x-deep-merge';\nimport { forEach, isFunction, isObject } from '@empathyco/x-utils';\nimport { MutableSchema, Schema } from './types';\n\n/**\n * Collection of internal method names for {@link MutableSchema | mutable schemas}.\n */\nconst mutableSchemasInternalMethods: string[] = ['$replace', '$override', '$extends', 'toString'];\n\n/**\n * Creates a {@link MutableSchema | mutable schema } version of a given {@link Schema | schema}.\n *\n * @param schema - The {@link Schema | schema} to make mutable.\n *\n * @returns A {@link MutableSchema | mutable schema} version of the given {@link Schema | schema}.\n *\n * @public\n */\nexport function createMutableSchema<Source, Target>(\n  schema: Schema<Source, Target>\n): MutableSchema<Source, Target> {\n  return {\n    ...schema,\n    $replace(newSchema) {\n      forEach(this, key => {\n        if (isInternalMethod(key as string)) {\n          return;\n        }\n        delete this[key];\n      });\n      Object.assign(this, newSchema);\n      /* We are replacing the schema with a completely new schema , so it makes sense that TS\n       complains that the old schema and the new one are not the same. */\n      return this as any;\n    },\n    $override(newSchema) {\n      return deepMerge(this, newSchema);\n    },\n    $extends(newSchema) {\n      return deepMerge({}, this, newSchema);\n    },\n    toString(includeInternalMethods = false) {\n      return serialize(this, !!includeInternalMethods);\n    }\n  };\n}\n\n/**\n * Checks if the given key is a {@link MutableSchema | mutableSchema} method.\n *\n * @param name - The key to check.\n *\n * @returns True if it is a {@link MutableSchema | mutableSchema} method,\n * false otherwise.\n *\n * @public\n */\nexport function isInternalMethod(name: string): boolean {\n  return mutableSchemasInternalMethods.includes(name);\n}\n\n/**\n * Returns a string representing of the given object.\n *\n * @param data - The object to get the string representation from.\n * @param includeInternalMethods - Flag to include in the string representation\n * the internal methods. Disabled by default.\n * @param deep - The level of indentation.\n * @returns The string representation.\n */\nfunction serialize(\n  data: Record<string, unknown>,\n  includeInternalMethods: boolean,\n  deep = 0\n): string {\n  const indentation = '  '.repeat(deep);\n  let output = '';\n  forEach(data, (key, value) => {\n    if (isObject(value)) {\n      output += `${indentation}${key}: {\\n${serialize(\n        value,\n        includeInternalMethods,\n        ++deep\n      )}${indentation}},\\n`;\n    } else if (!isFunction(value) || !isInternalMethod(key) || includeInternalMethods) {\n      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n      output += `${indentation}${key}: ${value},\\n`;\n    }\n  });\n  return output;\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/schemas/utils.ts"],"names":[],"mappings":";;;AAAA,0DAAoD;AACpD,gDAAmE;AAGnE;;GAEG;AACH,MAAM,6BAA6B,GAAa,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,MAA8B;IAE9B,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,CAAC,SAAS;YAChB,IAAA,iBAAO,EAAC,IAAI,EAAE,GAAG,CAAC,EAAE;gBAClB,IAAI,gBAAgB,CAAC,GAAa,CAAC,EAAE;oBACnC,OAAO;iBACR;gBACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/B;+EACmE;YACnE,OAAO,IAAW,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,SAAS;YACjB,OAAO,IAAA,wBAAS,EAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;QACD,QAAQ,CAAC,SAAkB;YACzB,OAAO,IAAA,wBAAS,EAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;QACD,QAAQ,CAAC,sBAAsB,GAAG,KAAK;YACrC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AA3BD,kDA2BC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,OAAO,6BAA6B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAFD,4CAEC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,IAA6B,EAC7B,sBAA+B,EAC/B,IAAI,GAAG,CAAC;IAER,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAA,iBAAO,EAAC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,IAAA,kBAAQ,EAAC,KAAK,CAAC,EAAE;YACnB,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,QAAQ,SAAS,CAC7C,KAAK,EACL,sBAAsB,EACtB,EAAE,IAAI,CACP,GAAG,WAAW,MAAM,CAAC;SACvB;aAAM,IAAI,CAAC,IAAA,oBAAU,EAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,sBAAsB,EAAE;YACjF,4EAA4E;YAC5E,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,KAAK,KAAK,KAAK,CAAC;SAC/C;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { deepMerge } from '@empathyco/x-deep-merge';\nimport { forEach, isFunction, isObject } from '@empathyco/x-utils';\nimport { MutableSchema, Schema } from './types';\n\n/**\n * Collection of internal method names for {@link MutableSchema | mutable schemas}.\n */\nconst mutableSchemasInternalMethods: string[] = ['$replace', '$override', '$extends', 'toString'];\n\n/**\n * Creates a {@link MutableSchema | mutable schema } version of a given {@link Schema | schema}.\n *\n * @param schema - The {@link Schema | schema} to make mutable.\n *\n * @returns A {@link MutableSchema | mutable schema} version of the given {@link Schema | schema}.\n *\n * @public\n */\nexport function createMutableSchema<Source, Target>(\n  schema: Schema<Source, Target>\n): MutableSchema<Source, Target> {\n  return {\n    ...schema,\n    $replace(newSchema) {\n      forEach(this, key => {\n        if (isInternalMethod(key as string)) {\n          return;\n        }\n        delete this[key];\n      });\n      Object.assign(this, newSchema);\n      /* We are replacing the schema with a completely new schema , so it makes sense that TS\n       complains that the old schema and the new one are not the same. */\n      return this as any;\n    },\n    $override(newSchema) {\n      return deepMerge(this, newSchema);\n    },\n    $extends(newSchema: unknown) {\n      return deepMerge({}, this, newSchema);\n    },\n    toString(includeInternalMethods = false) {\n      return serialize(this, !!includeInternalMethods);\n    }\n  };\n}\n\n/**\n * Checks if the given key is a {@link MutableSchema | mutableSchema} method.\n *\n * @param name - The key to check.\n *\n * @returns True if it is a {@link MutableSchema | mutableSchema} method,\n * false otherwise.\n *\n * @public\n */\nexport function isInternalMethod(name: string): boolean {\n  return mutableSchemasInternalMethods.includes(name);\n}\n\n/**\n * Returns a string representing of the given object.\n *\n * @param data - The object to get the string representation from.\n * @param includeInternalMethods - Flag to include in the string representation\n * the internal methods. Disabled by default.\n * @param deep - The level of indentation.\n * @returns The string representation.\n */\nfunction serialize(\n  data: Record<string, unknown>,\n  includeInternalMethods: boolean,\n  deep = 0\n): string {\n  const indentation = '  '.repeat(deep);\n  let output = '';\n  forEach(data, (key, value) => {\n    if (isObject(value)) {\n      output += `${indentation}${key}: {\\n${serialize(\n        value,\n        includeInternalMethods,\n        ++deep\n      )}${indentation}},\\n`;\n    } else if (!isFunction(value) || !isInternalMethod(key) || includeInternalMethods) {\n      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n      output += `${indentation}${key}: ${value},\\n`;\n    }\n  });\n  return output;\n}\n"]}

package/dist/esm/schemas/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/schemas/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  AnyFunction,\n  DeepPartial,\n  ExtractPath,\n  ExtractPathByType,\n  ExtractType,\n  Primitive\n} from '@empathyco/x-utils';\nimport { MapperContext } from '../mappers/types';\n\n// TODO: EX-5830 - Enhance Schema type to support optional properties in the Source object\n/**\n * Template object to transform a source object to a target object.\n *\n * @remarks The source object must not have optional properties, as it could cause infinite\n * type instantiations.\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     price: {\n *       max: number;\n *       min: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     maxPrice: number;\n *     minPrice: number;\n *     img: string[]\n *   }\n *\n *   const schema: Schema<Source, Target> = {\n *     identifier: 'id',\n *     maxPrice: 'price.max',\n *     minPrice: ({ price }) => Math.min(0, price.min),\n *     img: 'images'\n *   };\n * ```\n * @public\n */\nexport type Schema<Source = any, Target = any> = {\n  [TargetKey in keyof Target]: SchemaTransformer<Source, Target, TargetKey>;\n};\n\n/**\n * A {@link Schema | schema} with extended functionality to: completely replace\n * the original schema, partially override it or create a new one.\n *\n * @param OriginalSchema - The {@link Schema | schema} that will be mutable.\n * @public\n */\nexport type MutableSchema<Source, Target> = Schema<Source, Target> & {\n  /**\n   * Replaces all usages of the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use instead of the original one.\n   * @returns The new {@link Schema | schema} that will be used.\n   */\n  $replace<NewSource, NewTarget>(\n    newSchema: Schema<NewSource, NewTarget>\n  ): MutableSchema<NewSource, NewTarget>;\n  /**\n   * Merges the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use to merge with the original one.\n   * @returns The {@link Schema | schema} returned by the merge.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $override<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Creates a new {@link Schema | schema} using the original one as starting point.\n   * The original {@link Schema | schema} will remain unchanged.\n   *\n   * @param newSchema - The {@link Schema | schema} to be used to extend the original one.\n   * @returns The {@link Schema | schema} created.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $extends<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Returns a string representing of the {@link Schema | schema}.\n   *\n   * @param includeInternalMethods - Flag to include in the string representation\n   * the internal methods. Disabled by default.\n   * @returns The string representation.\n   */\n  toString(includeInternalMethods?: boolean): string;\n};\n/**\n * The possible transformers to apply to the target key.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param TargetKey - The target key to apply the transformation.\n * @public\n */\nexport type SchemaTransformer<Source, Target, TargetKey extends keyof Target> =\n  | PathTransformer<Source, Target[TargetKey]>\n  | FunctionTransformer<Source, Target[TargetKey]>\n  | SubSchemaTransformer<Source, Target[TargetKey]>\n  | Schema<Source, Exclude<Target[TargetKey], AnyFunction | Primitive>>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: 'id',\n *     hits: 'count'\n *   };\n *\n *   const wrongSubSchema: Schema<Source, Target> = {\n *     // @ts-expect-error\n *     title: 'count', // This raises a TS error\n *     hits: 'count'\n *   };\n * ```\n * @public\n */\nexport type PathTransformer<Source, Target> = ExtractPathByType<Source, Target>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: source => source.id,\n *     hits: (source, context) => context.requestParameters.query === 'example'\n *      ? source.count\n *      : 0\n *   };\n * ```\n * @public\n */\nexport type FunctionTransformer<Source, Target> = (\n  source: Source,\n  context?: MapperContext\n) => Target;\n\n/**\n * An object containing a schema narrowing its source object based on the given path.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     facets: {\n *       name: string;\n *       count: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     filters: {\n *       id: string;\n *       numFound: number;\n *     };\n *     img: string[]\n *   }\n *\n *   const subSchema: SubSchemaTransformer<Source, Target['filters']> = {\n *     $path: 'facets',\n *     $subSchema: {\n *       id: 'name',\n *       numFound: 'count'\n *     }\n *   };\n * ```\n * @public\n */\nexport type SubSchemaTransformer<Source, Target> = {\n  [Path in ExtractPath<Source>]: {\n    $context?: MapperContext;\n    $path: Path;\n    $subSchema:\n      | SubSchema<Source, Target, Path>\n      | '$self'\n      | ((source: Source) => SubSchema<Source, Target, Path>);\n  };\n}[ExtractPath<Source>];\n\n/**\n * A {@link Schema | schema} that will be applied to an inner path of an object.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param Path - The path where the schema will be applied.\n * @public\n */\nexport type SubSchema<Source, Target, Path extends ExtractPath<Source>> = ExtractType<\n  Source,\n  Path\n> extends (infer SourceArrayType)[]\n  ? Target extends (infer TargetArrayType)[]\n    ? Schema<SourceArrayType, TargetArrayType>\n    : never\n  : Target extends []\n  ? never\n  : Schema<ExtractType<Source, Path>, Target>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/schemas/types.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  AnyFunction,\n  DeepPartial,\n  ExtractPath,\n  ExtractPathByType,\n  ExtractType,\n  Primitive\n} from '@empathyco/x-utils';\nimport { MapperContext } from '../mappers/types';\n\n// TODO: EX-5830 - Enhance Schema type to support optional properties in the Source object\n/**\n * Template object to transform a source object to a target object.\n *\n * @remarks The source object must not have optional properties, as it could cause infinite\n * type instantiations.\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     price: {\n *       max: number;\n *       min: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     maxPrice: number;\n *     minPrice: number;\n *     img: string[]\n *   }\n *\n *   const schema: Schema<Source, Target> = {\n *     identifier: 'id',\n *     maxPrice: 'price.max',\n *     minPrice: ({ price }) => Math.min(0, price.min),\n *     img: 'images'\n *   };\n * ```\n * @public\n */\nexport type Schema<Source = any, Target = any> = {\n  [TargetKey in keyof Target]: SchemaTransformer<Source, Target, TargetKey>;\n};\n\n/**\n * A {@link Schema | schema} with extended functionality to: completely replace\n * the original schema, partially override it or create a new one.\n *\n * @param OriginalSchema - The {@link Schema | schema} that will be mutable.\n * @public\n */\nexport type MutableSchema<Source, Target> = Schema<Source, Target> & {\n  /**\n   * Replaces all usages of the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use instead of the original one.\n   * @returns The new {@link Schema | schema} that will be used.\n   */\n  $replace<NewSource, NewTarget>(\n    newSchema: Schema<NewSource, NewTarget>\n  ): MutableSchema<NewSource, NewTarget>;\n  /**\n   * Merges the original {@link Schema | schema} with the given one.\n   *\n   * @param newSchema - The {@link Schema | schema} to use to merge with the original one.\n   * @returns The {@link Schema | schema} returned by the merge.\n   */\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $override<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Creates a new {@link Schema | schema} using the original one as starting point.\n   * The original {@link Schema | schema} will remain unchanged.\n   *\n   * @param newSchema - The {@link Schema | schema} to be used to extend the original one.\n   * Both schema's Target and Source can be unique or also be extending from another one.\n   * @returns The {@link Schema | schema} created.\n   */\n  $extends<NewSource extends Source, NewTarget extends Target>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, Omit<NewTarget, keyof Target>>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  // eslint-disable-next-line @typescript-eslint/ban-types\n  $extends<NewSource, NewTarget = {}>(\n    newSchema: DeepPartial<Schema<Source & NewSource, Target>> &\n      Schema<Source & NewSource, NewTarget>\n  ): MutableSchema<Source & NewSource, Target & NewTarget>;\n  /**\n   * Returns a string representing of the {@link Schema | schema}.\n   *\n   * @param includeInternalMethods - Flag to include in the string representation\n   * the internal methods. Disabled by default.\n   * @returns The string representation.\n   */\n  toString(includeInternalMethods?: boolean): string;\n};\n/**\n * The possible transformers to apply to the target key.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param TargetKey - The target key to apply the transformation.\n * @public\n */\nexport type SchemaTransformer<Source, Target, TargetKey extends keyof Target> =\n  | PathTransformer<Source, Target[TargetKey]>\n  | FunctionTransformer<Source, Target[TargetKey]>\n  | SubSchemaTransformer<Source, Target[TargetKey]>\n  | Schema<Source, Exclude<Target[TargetKey], AnyFunction | Primitive>>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: 'id',\n *     hits: 'count'\n *   };\n *\n *   const wrongSubSchema: Schema<Source, Target> = {\n *     // @ts-expect-error\n *     title: 'count', // This raises a TS error\n *     hits: 'count'\n *   };\n * ```\n * @public\n */\nexport type PathTransformer<Source, Target> = ExtractPathByType<Source, Target>;\n\n/**\n * A function with the source object and mapper context as parameters that returns the value of a\n * target's property.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     count: number;\n *   }\n *\n *   interface Target {\n *     title: string;\n *     hits: number;\n *   }\n *\n *   const subSchema: Schema<Source, Target> = {\n *     title: source => source.id,\n *     hits: (source, context) => context.requestParameters.query === 'example'\n *      ? source.count\n *      : 0\n *   };\n * ```\n * @public\n */\nexport type FunctionTransformer<Source, Target> = (\n  source: Source,\n  context?: MapperContext\n) => Target;\n\n/**\n * An object containing a schema narrowing its source object based on the given path.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @example\n * ```typescript\n *  interface Source {\n *     id: string;\n *     facets: {\n *       name: string;\n *       count: number;\n *     };\n *     images: string[];\n *   }\n *\n *   interface Target {\n *     identifier: string;\n *     filters: {\n *       id: string;\n *       numFound: number;\n *     };\n *     img: string[]\n *   }\n *\n *   const subSchema: SubSchemaTransformer<Source, Target['filters']> = {\n *     $path: 'facets',\n *     $subSchema: {\n *       id: 'name',\n *       numFound: 'count'\n *     }\n *   };\n * ```\n * @public\n */\nexport type SubSchemaTransformer<Source, Target> = {\n  [Path in ExtractPath<Source>]: {\n    $context?: MapperContext;\n    $path: Path;\n    $subSchema:\n      | SubSchema<Source, Target, Path>\n      | '$self'\n      | ((source: Source) => SubSchema<Source, Target, Path>);\n  };\n}[ExtractPath<Source>];\n\n/**\n * A {@link Schema | schema} that will be applied to an inner path of an object.\n *\n * @param Source - The source object.\n * @param Target - The target object.\n * @param Path - The path where the schema will be applied.\n * @public\n */\nexport type SubSchema<Source, Target, Path extends ExtractPath<Source>> = ExtractType<\n  Source,\n  Path\n> extends (infer SourceArrayType)[]\n  ? Target extends (infer TargetArrayType)[]\n    ? Schema<SourceArrayType, TargetArrayType>\n    : never\n  : Target extends []\n  ? never\n  : Schema<ExtractType<Source, Path>, Target>;\n"]}

package/dist/esm/schemas/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/schemas/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnE;;GAEG;AACH,MAAM,6BAA6B,GAAa,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA8B;IAE9B,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,CAAC,SAAS;YAChB,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;gBAClB,IAAI,gBAAgB,CAAC,GAAa,CAAC,EAAE;oBACnC,OAAO;iBACR;gBACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/B;+EACmE;YACnE,OAAO,IAAW,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,SAAS;YACjB,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;QACD,QAAQ,CAAC,SAAS;YAChB,OAAO,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;QACD,QAAQ,CAAC,sBAAsB,GAAG,KAAK;YACrC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,6BAA6B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,IAA6B,EAC7B,sBAA+B,EAC/B,IAAI,GAAG,CAAC;IAER,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE;YACnB,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,QAAQ,SAAS,CAC7C,KAAK,EACL,sBAAsB,EACtB,EAAE,IAAI,CACP,GAAG,WAAW,MAAM,CAAC;SACvB;aAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,sBAAsB,EAAE;YACjF,4EAA4E;YAC5E,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,KAAK,KAAK,KAAK,CAAC;SAC/C;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { deepMerge } from '@empathyco/x-deep-merge';\nimport { forEach, isFunction, isObject } from '@empathyco/x-utils';\nimport { MutableSchema, Schema } from './types';\n\n/**\n * Collection of internal method names for {@link MutableSchema | mutable schemas}.\n */\nconst mutableSchemasInternalMethods: string[] = ['$replace', '$override', '$extends', 'toString'];\n\n/**\n * Creates a {@link MutableSchema | mutable schema } version of a given {@link Schema | schema}.\n *\n * @param schema - The {@link Schema | schema} to make mutable.\n *\n * @returns A {@link MutableSchema | mutable schema} version of the given {@link Schema | schema}.\n *\n * @public\n */\nexport function createMutableSchema<Source, Target>(\n  schema: Schema<Source, Target>\n): MutableSchema<Source, Target> {\n  return {\n    ...schema,\n    $replace(newSchema) {\n      forEach(this, key => {\n        if (isInternalMethod(key as string)) {\n          return;\n        }\n        delete this[key];\n      });\n      Object.assign(this, newSchema);\n      /* We are replacing the schema with a completely new schema , so it makes sense that TS\n       complains that the old schema and the new one are not the same. */\n      return this as any;\n    },\n    $override(newSchema) {\n      return deepMerge(this, newSchema);\n    },\n    $extends(newSchema) {\n      return deepMerge({}, this, newSchema);\n    },\n    toString(includeInternalMethods = false) {\n      return serialize(this, !!includeInternalMethods);\n    }\n  };\n}\n\n/**\n * Checks if the given key is a {@link MutableSchema | mutableSchema} method.\n *\n * @param name - The key to check.\n *\n * @returns True if it is a {@link MutableSchema | mutableSchema} method,\n * false otherwise.\n *\n * @public\n */\nexport function isInternalMethod(name: string): boolean {\n  return mutableSchemasInternalMethods.includes(name);\n}\n\n/**\n * Returns a string representing of the given object.\n *\n * @param data - The object to get the string representation from.\n * @param includeInternalMethods - Flag to include in the string representation\n * the internal methods. Disabled by default.\n * @param deep - The level of indentation.\n * @returns The string representation.\n */\nfunction serialize(\n  data: Record<string, unknown>,\n  includeInternalMethods: boolean,\n  deep = 0\n): string {\n  const indentation = '  '.repeat(deep);\n  let output = '';\n  forEach(data, (key, value) => {\n    if (isObject(value)) {\n      output += `${indentation}${key}: {\\n${serialize(\n        value,\n        includeInternalMethods,\n        ++deep\n      )}${indentation}},\\n`;\n    } else if (!isFunction(value) || !isInternalMethod(key) || includeInternalMethods) {\n      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n      output += `${indentation}${key}: ${value},\\n`;\n    }\n  });\n  return output;\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/schemas/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnE;;GAEG;AACH,MAAM,6BAA6B,GAAa,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA8B;IAE9B,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,CAAC,SAAS;YAChB,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;gBAClB,IAAI,gBAAgB,CAAC,GAAa,CAAC,EAAE;oBACnC,OAAO;iBACR;gBACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/B;+EACmE;YACnE,OAAO,IAAW,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,SAAS;YACjB,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;QACD,QAAQ,CAAC,SAAkB;YACzB,OAAO,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;QACD,QAAQ,CAAC,sBAAsB,GAAG,KAAK;YACrC,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,6BAA6B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,IAA6B,EAC7B,sBAA+B,EAC/B,IAAI,GAAG,CAAC;IAER,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE;YACnB,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,QAAQ,SAAS,CAC7C,KAAK,EACL,sBAAsB,EACtB,EAAE,IAAI,CACP,GAAG,WAAW,MAAM,CAAC;SACvB;aAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,sBAAsB,EAAE;YACjF,4EAA4E;YAC5E,MAAM,IAAI,GAAG,WAAW,GAAG,GAAG,KAAK,KAAK,KAAK,CAAC;SAC/C;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { deepMerge } from '@empathyco/x-deep-merge';\nimport { forEach, isFunction, isObject } from '@empathyco/x-utils';\nimport { MutableSchema, Schema } from './types';\n\n/**\n * Collection of internal method names for {@link MutableSchema | mutable schemas}.\n */\nconst mutableSchemasInternalMethods: string[] = ['$replace', '$override', '$extends', 'toString'];\n\n/**\n * Creates a {@link MutableSchema | mutable schema } version of a given {@link Schema | schema}.\n *\n * @param schema - The {@link Schema | schema} to make mutable.\n *\n * @returns A {@link MutableSchema | mutable schema} version of the given {@link Schema | schema}.\n *\n * @public\n */\nexport function createMutableSchema<Source, Target>(\n  schema: Schema<Source, Target>\n): MutableSchema<Source, Target> {\n  return {\n    ...schema,\n    $replace(newSchema) {\n      forEach(this, key => {\n        if (isInternalMethod(key as string)) {\n          return;\n        }\n        delete this[key];\n      });\n      Object.assign(this, newSchema);\n      /* We are replacing the schema with a completely new schema , so it makes sense that TS\n       complains that the old schema and the new one are not the same. */\n      return this as any;\n    },\n    $override(newSchema) {\n      return deepMerge(this, newSchema);\n    },\n    $extends(newSchema: unknown) {\n      return deepMerge({}, this, newSchema);\n    },\n    toString(includeInternalMethods = false) {\n      return serialize(this, !!includeInternalMethods);\n    }\n  };\n}\n\n/**\n * Checks if the given key is a {@link MutableSchema | mutableSchema} method.\n *\n * @param name - The key to check.\n *\n * @returns True if it is a {@link MutableSchema | mutableSchema} method,\n * false otherwise.\n *\n * @public\n */\nexport function isInternalMethod(name: string): boolean {\n  return mutableSchemasInternalMethods.includes(name);\n}\n\n/**\n * Returns a string representing of the given object.\n *\n * @param data - The object to get the string representation from.\n * @param includeInternalMethods - Flag to include in the string representation\n * the internal methods. Disabled by default.\n * @param deep - The level of indentation.\n * @returns The string representation.\n */\nfunction serialize(\n  data: Record<string, unknown>,\n  includeInternalMethods: boolean,\n  deep = 0\n): string {\n  const indentation = '  '.repeat(deep);\n  let output = '';\n  forEach(data, (key, value) => {\n    if (isObject(value)) {\n      output += `${indentation}${key}: {\\n${serialize(\n        value,\n        includeInternalMethods,\n        ++deep\n      )}${indentation}},\\n`;\n    } else if (!isFunction(value) || !isInternalMethod(key) || includeInternalMethods) {\n      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n      output += `${indentation}${key}: ${value},\\n`;\n    }\n  });\n  return output;\n}\n"]}

package/dist/types/schemas/types.d.ts

@@ -64,8 +64,10 @@ export declare type MutableSchema<Source, Target> = Schema<Source, Target> & {
      * The original {@link Schema | schema} will remain unchanged.
      *
      * @param newSchema - The {@link Schema | schema} to be used to extend the original one.
+     * Both schema's Target and Source can be unique or also be extending from another one.
      * @returns The {@link Schema | schema} created.
      */
+    $extends<NewSource extends Source, NewTarget extends Target>(newSchema: DeepPartial<Schema<Source & NewSource, Target>> & Schema<Source & NewSource, Omit<NewTarget, keyof Target>>): MutableSchema<Source & NewSource, Target & NewTarget>;
     $extends<NewSource, NewTarget = {}>(newSchema: DeepPartial<Schema<Source & NewSource, Target>> & Schema<Source & NewSource, NewTarget>): MutableSchema<Source & NewSource, Target & NewTarget>;
     /**
      * Returns a string representing of the {@link Schema | schema}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empathyco/x-adapter",
-  "version": "8.0.0-alpha.17",
+  "version": "8.0.0-alpha.19",
   "description": "A utils library to create a client for any API",
   "author": "Empathy Systems Corporation S.L.",
   "license": "Apache-2.0",
@@ -35,9 +35,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@empathyco/x-deep-merge": "^1.3.0-alpha.26",
-    "@empathyco/x-utils": "^1.0.0-alpha.12",
-    "tslib": "~2.3.0"
+    "@empathyco/x-deep-merge": "^1.3.0-alpha.27",
+    "@empathyco/x-utils": "^1.0.0-alpha.13",
+    "tslib": "~2.4.1"
   },
   "devDependencies": {
     "@types/jest": "~27.0.3",
@@ -50,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d691003af599189d0b6b993178e337acb4900e9e"
+  "gitHead": "b5640ccccd296584a4775a8db625f9039b6025e9"
 }