@remkoj/optimizely-graph-functions 2.0.3 → 2.1.0

package/README.md

@@ -1,99 +1,137 @@
-# Optimizely GraphQL Codegen Plugin
-GraphQL Codegen plugin and preset which generate both the GraphQL type definitions and a few convenienece methods for useage with [Optimizely Graph Client](../optimizely-graph-client/README.md).
-
-## Install package
-This package is provided as part of the example site mono-repository and thus doesn't need to be installed separately.
-
-## Configure package
-Create a codegen.ts within your application root folder (e.g. apps/frontend/codegen.ts within the example site). Within the codegen.ts create the following configuration:
-
-```typescript
-import type { CodegenConfig  } from '@graphql-codegen/cli'
-import getSchemaInfo from '@remkoj/optimizely-graph-client/codegen'
-import OptimizelyGraphPreset, {type PresetOptions as OptimizelyGraphPresetOptions}  from '@remkoj/optimizely-graph-functions/preset'
-
-// This example assumes the configuration can be read from the environment variables, make sure .env files (if you use them) are processed prior to invoking getSchemaInfo()
-
-// Create the configuration itself
-const config: CodegenConfig = {
-    schema: getSchemaInfo(),
-    documents: [
-        // Add local GQL files
-        'src/**/*.graphql',
-
-        // Add Definitions from components
-        'src/**/!(*.d).{ts,tsx}'
-    ],
-    generates: {
-        './gql/': {
-            preset: OptimizelyGraphPreset,
-            presetConfig: {
-                gqlTagName: 'gql',
-                injections: [
-                    {
-                        // Add from all pages, except colocated blocks
-                        into: "PageData",
-                        pathRegex: "src\/components\/page.*(?<!block\.tsx)$"
-                    },
-                    {
-                        // Add from all blocks, included blocks colocated with pages
-                        into: "BlockData",
-                        pathRegex: "src\/components\/(block.*|page.*block.[tj]s[x]{0,1})$"
-                    },
-                    {
-                        // Add from all blocks
-                        into: "BlockData",
-                        pathRegex: "src\/components\/block"
-                    }
-                ],
-            } as OptimizelyGraphPresetOptions
-        }
-    },
-    ignoreNoDocuments: false
-}
-
-export default config
-```
-
-## Usage
-After running the code generation, you can use the following API's (assuming the folder where the generated files are stored is available at '@gql'):
-
-### Option 1: Direct methods
-```typescript
-import { getContentById, getContentByPath } from '@gql'
-
-const client = /* fetch your client */
-
-const contentFromId = await getContentById(client, { guidValue: '00000000-0000-0000-0000-000000000000', locale: 'en' })
-const contentFromPath = await getContentByPath(client, { path: '/en' })
-```
-
-### Option 2: Enhanced Client
-```typescript
-import { OptimizelyGraphClient, Schema } from '@gql'
-
-const client = new OptimizelyGraphClient({
-    single_key: "your single key here"
-})
-const contentId = '00000000-0000-0000-0000-000000000000'
-const locale = Schema.Locales.En
-
-const contentItem = await client.getContentById({ guidValue: contentId, locale })
-```
-
-## Query Fragments
-The preset automatically injects the following fragments into your list of documents when generating the code. This allows optimization of the generated query size and normalize output so it can be used by the `CmsContent` and `CmsContentArea` components (Which are available in the `@remkoj/optimizely-dxp-react` package).
-
-The following GraphQL Fragments are available:
-
-| Name | Description |
-| --- | --- |
-| ContentLink | Get the fields needed from a ContentLink field, so it can be used to look up content |
-| ContentLinkSearch | Get the fields needed from a ContentLink field, so it can be used to look up content, within a searchable context |
-| IContentData | The fields on an IContent item needed by the `CmsContent` component to reliably determine the content type and load it's data
-| ContentAreaItemData | Retrieve the items within a *searchable* ContentArea on a **Page** component, so that the content can be rendered by the `CmsContentArea` component
-| BlockContentAreaItemData | Retrieve the items within a *non-searchable* ContentArea on a **Block** component, so that the content can be rendered by the `CmsContentArea` component |
-| BlockContentAreaItemSearchData | Retrieve the items within a *searchable* ContentArea on a **Block** component, so that the content can be rendered by the `CmsContentArea` component |
-| LinkItemData | |
-| ImageData | |
-| ImageDataSearch | |
+# Optimizely GraphQL Codegen Plugin
+GraphQL Codegen plugin and preset which generate both the GraphQL type definitions and a few convenienece methods for useage with [Optimizely Graph Client](../optimizely-graph-client/README.md).
+
+## Install package
+To install using Yarn, use the following command:
+
+```bash
+yarn add --dev @remkoj/optimizely-graph-functions
+```
+
+## Configure package
+Create a codegen.ts within your application root folder (e.g. apps/frontend/codegen.ts within the example site). Within the codegen.ts create the following configuration:
+
+```typescript
+import type { CodegenConfig  } from '@graphql-codegen/cli'
+import getSchemaInfo from '@remkoj/optimizely-graph-client/codegen'
+import OptimizelyGraphPreset, {type PresetOptions as OptimizelyGraphPresetOptions}  from '@remkoj/optimizely-graph-functions/preset'
+
+// This example assumes the configuration can be read from the environment variables, make sure .env files (if you use them) are processed prior to invoking getSchemaInfo()
+
+// Create the configuration itself
+const config: CodegenConfig = {
+    schema: getSchemaInfo(),
+    documents: [
+        // Add local GQL files
+        'src/**/*.graphql',
+
+        // Add Definitions from components
+        'src/**/!(*.d).{ts,tsx}'
+    ],
+    generates: {
+        './src/gql/': {
+            preset: OptimizelyGraphPreset,
+            presetConfig: {
+                // By default the preset will not support recursive queries, 
+                // however if your content model requires it, you can enable
+                // it here.
+                //
+                // When setting recursion to `true` it requires additional
+                // steps to work
+                recursion: false,
+
+                // The GQL tag to be used to identify inline GraphQL queries
+                gqlTagName: 'gql',
+
+                // Configure the fragments that will be spread into the utility
+                // partial fragments. You can use any fragment here, however 
+                // the system is designed for the following receiving 
+                // fragments:
+                // - PageData => For all page-level components
+                // - BlockData => For everyting that can be rendered as
+                //                individual component
+                // - ElementData => For all element types that are useable
+                //                  within Visual Builder
+                injections: [
+                    {
+                        // Add from all Pages, as .page.graphql file
+                        into: "PageData",
+                        pathRegex: "src\/components\/cms\/.*\.page\.graphql$"
+                    },
+                    {
+                        // Add from all Experiences, as .experience.graphql file
+                        into: "PageData",
+                        pathRegex: "src\/components\/cms\/.*\.experience\.graphql$"
+                    },
+                    {
+                        // Add from all Blocks, as .component.graphql file
+                        into: "BlockData",
+                        pathRegex: "src\/components\/cms\/.*\.component\.graphql$"
+                    },
+                    {
+                        // Add from all Elements, as .element.graphql file
+                        into: "ElementData",
+                        pathRegex: "src\/components\/cms\/.*\.element\.graphql$"
+                    }
+                ],
+            } as OptimizelyGraphPresetOptions
+        }
+    },
+    ignoreNoDocuments: false
+}
+
+export default config
+```
+
+The presetConfig of the `OptimizelyGraphPreset` is an extension of the configuration for the [Client Preset](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client) of GraphQL Codegen. It adds the following configuration options:
+
+| Configuration option | Usage |
+| --- | --- |
+| recursion | Set to `true` to automatically generate recursive queries to iterate down the result.<br><br>The default logic of GraphQL Codegen contains an infite loop when disabling the recursion check. To patch this, a custom resolution must be added to the root `package.json`. This resolution must set the resolution for `@graphql-codegen/visitor-plugin-common` to the patched file [provided within this repository](../../dependencies/graphql-codegen-visitor-plugin-common-v5.3.1-patched.tgz) |
+| injections | A set of rules to define how individual fragments will be used to construct the master queries. Each rule has the following options: <br/>- `into`:  The name of the Fragment to inject into<br/>- `pathRegex`: The regular expression to be applied ot the file name to see if the fragment should be included with the `into` Fragment<br/>- `nameRegex`: The regular expression to be applied to the name of the Fragment
+| documents | The standard rules for preset specific documents, however there are four standard documents available:<br/>- `opti-cms:/queries/13` (included by default)<br/>- `opti-cms:/queries/12`<br/>- `opti-cms:/fragments/13` (included by default)<br/>- `opti-cms:/fragments/12`<br/>*The defaults are only applied when there's no document starting with `opti-cms:` defined*
+| functions | The list of GraphQL Functions that should be made available in the `functions.ts` file. When specified, this overrides the default list.<br/>*Default value: `['getContentType','getContentByPath','getContentById']`*
+| verbose | Set to `true` to enable debugging output of the preset, loader, plugin and transform |
+
+
+## Usage
+After running the code generation, you can use the following API's (assuming the folder where the generated files are stored is available at `@/gql`):
+
+### Option 1: Direct methods
+Only the methods specified by the `functions` preset configuration are available using this method.
+
+```typescript
+import { getContentById, getContentByPath } from "@/gql/functions"
+import createClient from "@remkoj/optimizely-graph-client"
+
+const client = createClient({
+    single_key: "your single key here"
+})
+
+const contentFromId = await getContentById(client, { guidValue: '00000000-0000-0000-0000-000000000000', locale: 'en' })
+const contentFromPath = await getContentByPath(client, { path: '/en' })
+```
+
+### Option 2: Enhanced Client
+All GraphQL operations (e.g. Queries, Mutations, ...) defined within the documents are available using this method.
+
+```typescript
+import { getSdk } from "@/gql/client"
+import createClient from "@remkoj/optimizely-graph-client"
+
+const client = getSdk(createClient({
+    single_key: "your single key here"
+}))
+const contentId = '00000000-0000-0000-0000-000000000000'
+const locale = Schema.Locales.En
+
+const contentItem = await client.getContentById({ guidValue: contentId, locale })
+```
+
+## Query Fragments
+The preset automatically injects a number of fragments and documents into the generated code. These can be found in their respective document:
+
+- [`opti-cms:/queries/13`](./src/documents/queries.cms13.ts)
+- [`opti-cms:/queries/12`](./src/documents/queries.cms12.ts)
+- [`opti-cms:/fragments/13`](./src/documents/fragments.cms13.ts)
+- [`opti-cms:/fragments/12`](./src/documents/fragments.cms12.ts)

package/dist/documents/fragments.cms12.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string[];
+export default _default;

package/dist/documents/fragments.cms12.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = [
+    // Global required fragments
+    `fragment BlockData on IContent {
+    ...IContentData
+  }`,
+    `fragment PageData on IContent {
+    ...IContentData
+  }`,
+    // NextJS:Create CLI Compatibility
+    `fragment PageIContentListItem on ContentAreaItemModel {
+    item: ContentLink {
+      data: Expanded {
+        ...BlockData
+      }
+    }
+    displayOption:DisplayOption
+  }`,
+    `fragment PageIContentListItemSearch on ContentAreaItemModelSearch {
+    item: ContentLink {
+      data: Expanded {
+        ...BlockData
+      }
+    }
+    displayOption:DisplayOption
+  }`,
+    `fragment IContentListItem on ContentAreaItemModel {
+    item: ContentLink {
+      data: Expanded {
+        ...RecursiveBlockData
+      }
+    }
+    displayOption:DisplayOption
+  }`,
+    `fragment IContentListItemSearch on ContentAreaItemModelSearch {
+    item: ContentLink {
+      data: Expanded {
+        ...RecursiveBlockData
+      }
+    }
+    displayOption:DisplayOption
+  }`,
+    `fragment RecursiveBlockData on IContent {
+    ...IContentData
+  }`,
+    `fragment ReferenceData on ContentModelReference {
+    id: Id,
+    version: WorkId,
+    key: GuidValue
+    data: Expanded {
+      ...RecursiveBlockData
+    }
+  }`,
+    `fragment ReferenceDataSearch on ContentModelReferenceSearch {
+    id: Id,
+    version: WorkId,
+    key: GuidValue
+    data: Expanded {
+      ...RecursiveBlockData
+    }
+  }`,
+    `fragment BinaryData on BlobModel {
+    id: Id
+    url: Url
+  }`,
+    `fragment ContentLink on ContentModelReference {
+    id: Id,
+    version: WorkId,
+    key: GuidValue
+    data: Expanded {
+      ...RecursiveBlockData
+    }
+  }`,
+    `fragment ContentLinkSearch on ContentModelReferenceSearch {
+    id: Id,
+    version: WorkId,
+    key: GuidValue
+    data: Expanded {
+      ...RecursiveBlockData
+    }
+  }`,
+    `fragment LinkItemData on LinkItemNode {
+    children: Text
+    title: Title
+    href: Href
+    target: Target
+    content: ContentLink {
+      href: Url
+      data: Expanded {
+        path: RelativePath
+      }
+    }
+  }`,
+    `fragment LinkItemDataSearch on LinkItemNodeSearch {
+    children: Text
+    title: Title
+    href: Href
+    target: Target
+    content: ContentLink {
+      href: Url
+      data: Expanded {
+        path: RelativePath
+      }
+    }
+  }`,
+    // Original CMS 12 Fragments
+    `fragment IContentData on IContent {
+    contentType: ContentType
+    _metadata: ContentLink {
+      id: Id,
+      version: WorkId,
+      key: GuidValue
+    }
+    locale: Language {
+        name: Name
+    }
+    path:RelativePath
+    _type: __typename
+  }`,
+    `fragment ImageData on ContentModelReference {
+      ...ContentLink
+      url: Url
+      data: Expanded {
+        ...IContentData
+        url: Url
+        alt: Name 
+        path: RelativePath
+      }
+    }`,
+    `fragment ImageDataSearch on ContentModelReferenceSearch {
+      ...ContentLinkSearch
+      url: Url
+      data: Expanded {
+        ...IContentData
+        url: Url
+        alt: Name 
+        path: RelativePath
+      }
+    }`
+];
+//# sourceMappingURL=fragments.cms12.js.map

package/dist/documents/fragments.cms12.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.cms12.js","sourceRoot":"","sources":["../../src/documents/fragments.cms12.ts"],"names":[],"mappings":";;AAAA,kBAAe;IACb,4BAA4B;IAC5B;;IAEE;IACF;;IAEE;IAEF,kCAAkC;IAClC;;;;;;;IAOE;IACF;;;;;;;IAOE;IACF;;;;;;;IAOE;IACF;;;;;;;IAOE;IACF;;IAEE;IACF;;;;;;;IAOE;IACF;;;;;;;IAOE;IACF;;;IAGE;IAEF;;;;;;;IAOE;IACF;;;;;;;IAOE;IACF;;;;;;;;;;;IAWE;IACF;;;;;;;;;;;IAWE;IAEF,4BAA4B;IAC5B;;;;;;;;;;;;IAYE;IACA;;;;;;;;;MASE;IACF;;;;;;;;;MASE;CACL,CAAA"}

package/dist/documents/fragments.cms13.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string[];
+export default _default;

package/dist/documents/fragments.cms13.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = [
+    `fragment IContentData on _IContent
+    {
+        _metadata {
+            ...IContentInfo
+        }
+        _type: __typename
+    }`,
+    `fragment CompositionData on ICompositionNode {
+        name: displayName
+        layoutType: nodeType    
+        type
+        key
+        template: displayTemplateKey
+        settings: displaySettings {
+            key
+            value
+        }
+        ... on ICompositionStructureNode {
+            nodes @recursive(depth: 10) {
+                name: displayName
+            }
+        }
+        ... on ICompositionElementNode {
+            element {
+                ...ElementData
+            }
+        }
+    }`,
+    `fragment IElementData on _IElement {
+        _metadata {
+            ...IContentInfo
+        }
+        _type: __typename
+    }`,
+    `fragment ElementData on _IElement {
+        ...IElementData
+    }`,
+    `fragment BlockData on _IContent {
+        ...IContentData
+    }`,
+    `fragment PageData on _IContent {
+        ...IContentData
+    }`,
+    `fragment LinkData on ContentUrl {
+        base
+        hierarchical
+        default
+    }`,
+    `fragment ReferenceData on ContentReference {
+        key
+        url {
+            ...LinkData
+        }
+    }`,
+    `fragment IContentInfo on IContentMetadata {
+        key
+        locale
+        types
+        displayName
+        version
+        url {
+            ...LinkData
+        }
+    }`,
+    `fragment IContentListItem on _IContent {
+        ...IContentData
+    }`,
+    `fragment ExperienceData on _IExperience {
+        composition {
+            ...CompositionData
+        }
+    }`,
+    `fragment LinkItemData on Link {
+        title
+        text
+        target
+        url {
+            ...LinkData
+        }
+    }`
+];
+//# sourceMappingURL=fragments.cms13.js.map

package/dist/documents/fragments.cms13.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.cms13.js","sourceRoot":"","sources":["../../src/documents/fragments.cms13.ts"],"names":[],"mappings":";;AAAA,kBAAe;IACX;;;;;;MAME;IACF;;;;;;;;;;;;;;;;;;;;MAoBE;IACF;;;;;MAKE;IACF;;MAEE;IACF;;MAEE;IACF;;MAEE;IACF;;;;MAIE;IACF;;;;;MAKE;IACF;;;;;;;;;MASE;IACF;;MAEE;IACF;;;;MAIE;IACF;;;;;;;MAOE;CACL,CAAA"}

package/dist/documents/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The list of standard properties
+ *
+ * @deprecated  Should not be used from @remkoj/optimizely-graph-functions, as it's a development only package
+ */
+export declare const IContentDataProps: string[];
+/**
+ * The standard (rawSDL) fragments for Optimizely CMS 13
+ *
+ * @deprecated  Not intended to be used outside of the @remkoj/optimizely-graph-functions package
+ */
+export declare const fragments: string[];
+/**
+ * The standard (rawSDL) fragments for Optimizely CMS 13
+ *
+ * @deprecated  Not intended to be used outside of the @remkoj/optimizely-graph-functions package
+ */
+export declare const queries: string[];

package/dist/documents/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queries = exports.fragments = exports.IContentDataProps = void 0;
+const fragments_cms13_1 = __importDefault(require("./fragments.cms13"));
+const queries_cms13_1 = __importDefault(require("./queries.cms13"));
+/**
+ * The list of standard properties
+ *
+ * @deprecated  Should not be used from @remkoj/optimizely-graph-functions, as it's a development only package
+ */
+exports.IContentDataProps = ["contentType", "id", "locale", "path", "__typename"];
+/**
+ * The standard (rawSDL) fragments for Optimizely CMS 13
+ *
+ * @deprecated  Not intended to be used outside of the @remkoj/optimizely-graph-functions package
+ */
+exports.fragments = fragments_cms13_1.default;
+/**
+ * The standard (rawSDL) fragments for Optimizely CMS 13
+ *
+ * @deprecated  Not intended to be used outside of the @remkoj/optimizely-graph-functions package
+ */
+exports.queries = queries_cms13_1.default;
+//# sourceMappingURL=index.js.map

package/dist/documents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/documents/index.ts"],"names":[],"mappings":";;;;;;AAAA,wEAA8C;AAC9C,oEAA0C;AAE1C;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,CAAC,aAAa,EAAC,IAAI,EAAC,QAAQ,EAAC,MAAM,EAAC,YAAY,CAAC,CAAA;AAElF;;;;GAIG;AACU,QAAA,SAAS,GAAG,yBAAc,CAAA;AAEvC;;;;GAIG;AACU,QAAA,OAAO,GAAG,uBAAY,CAAA"}

package/dist/documents/queries.cms12.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string[];
+export default _default;

package/dist/documents/queries.cms12.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = [
+    `query getContentById($id: Int, $workId: Int, $guidValue: String, $locale: [Locales!], $isCommonDraft: Boolean) {
+        content: Content(
+            where: {
+                ContentLink: { 
+                    Id: { eq: $id }, 
+                    WorkId: { eq: $workId }, 
+                    GuidValue: { eq: $guidValue } 
+                }
+                IsCommonDraft: { eq: $isCommonDraft }
+            }
+            locale: $locale
+        ) {
+            total
+            items {
+                ...IContentData
+                ...PageData
+                ...BlockData
+            }
+        }
+    }`,
+    `query getContentByPath($path: String!, $locale: [Locales], $siteId: String) {
+        content: Content(
+            where: {
+                RelativePath: {
+                    eq: $path
+                }
+                SiteId: {
+                    eq: $siteId
+                }
+            },
+            locale: $locale
+        ) {
+            items {
+                ...PageData
+            }
+        }
+    }`,
+    `query getContentType($id: Int, $workId: Int, $guidValue: String, $locale: [Locales]) {
+        content: Content(
+            where: {
+                ContentLink: {
+                    GuidValue: {
+                        eq: $guidValue
+                    }
+                    Id: {
+                        eq: $id
+                    },
+                    WorkId: {
+                        eq: $workId
+                    }
+                }
+            },
+            locale: $locale
+            limit: 1
+        ) {
+            items {
+                ContentType
+            },
+            total
+        }
+    }`
+];
+//# sourceMappingURL=queries.cms12.js.map

package/dist/documents/queries.cms12.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.cms12.js","sourceRoot":"","sources":["../../src/documents/queries.cms12.ts"],"names":[],"mappings":";;AAAA,kBAAe;IACX;;;;;;;;;;;;;;;;;;;MAmBE;IACF;;;;;;;;;;;;;;;;MAgBE;IACF;;;;;;;;;;;;;;;;;;;;;;;MAuBE;CACL,CAAA"}

package/dist/documents/queries.cms13.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string[];
+export default _default;

package/dist/documents/queries.cms13.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = [
+    `query getContentById($key: String!, $version: String, $locale: [Locales!], $path: String, $domain: String) {
+        content: _Content(
+            where: {
+                _or: [
+                    { _metadata: { key: { eq: $key }, version: { eq: $version } } }
+                    { _metadata: { url: { hierarchical: { eq: $path }, base: { eq: $domain } }, version: { eq: $version } } }
+                ]
+            }
+            locale: $locale
+        ) {
+            total
+            items {
+                ...BlockData
+                ...PageData
+            }
+        }
+    }`,
+    `query getContentByPath($path: String!, $version: String, $locale: [Locales!], $domain: String) {
+        content: _Content(
+            where: {
+                _metadata: { url: { default: { eq: $path }, base: { eq: $domain } }, version: { eq: $version }}
+            }
+            locale: $locale
+        ) {
+            total
+            items {
+                ...PageData
+            }
+        }
+    }`,
+    `query getContentType($key: String!, $version: String, $locale: [Locales!], $path: String, $domain: String) {
+        content: _Content(
+            where: {
+                _or: [
+                    { _metadata: { key: { eq: $key }, version: { eq: $version } } }
+                    { _metadata: { url: { hierarchical: { eq: $path }, base: { eq: $domain } }, version: { eq: $version } } }
+                ]
+            }
+            locale: $locale
+        ) {
+            total
+            items {
+                _metadata {
+                    types
+                }
+            }
+        }
+    }`
+];
+//# sourceMappingURL=queries.cms13.js.map