@financial-times/dotcom-server-app-context 7.3.1 → 7.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/dotcom-server-app-context",
-  "version": "7.3.1",
+  "version": "7.3.2",
   "description": "",
   "main": "dist/node/index.js",
   "types": "src/index.ts",
@@ -30,7 +30,8 @@
     "npm": "7.x || 8.x"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "src/"
   ],
   "repository": {
     "type": "git",

package/src/AppContext.ts

@@ -0,0 +1,33 @@
+import { TAppContext } from './types'
+import validate from './validate'
+import filterEmptyData from './filterEmptyData'
+
+export type TAppContextOptions = {
+  appContext?: Partial<TAppContext>
+}
+
+export class AppContext {
+  private data: Partial<TAppContext> = {}
+
+  constructor(options: TAppContextOptions = {}) {
+    const data = filterEmptyData({ ...options.appContext })
+
+    for (const [property, value] of Object.entries(data)) {
+      this.set(property, value)
+    }
+  }
+
+  get(property: string) {
+    return this.data[property]
+  }
+
+  set(property: string, value: any) {
+    if (validate(property, value)) {
+      this.data[property] = value
+    }
+  }
+
+  getAll(): Partial<TAppContext> {
+    return Object.freeze({ ...this.data })
+  }
+}

package/src/__test__/AppContext.spec.ts

@@ -0,0 +1,75 @@
+import { AppContext } from '../AppContext'
+import * as fixtures from './__fixtures__/contextData'
+
+describe('dotcom-server-app-context/src/AppContext', () => {
+  describe('constructor', () => {
+    let instance
+
+    beforeAll(() => {
+      instance = new AppContext({ appContext: fixtures.validAppContext })
+    })
+
+    it('sets the given app context data', () => {
+      expect(instance.data).toEqual(fixtures.validAppContext)
+    })
+
+    describe('invalid data', () => {
+      it('throws if any app context data is invalid', () => {
+        const init = () =>
+          new AppContext({
+            appContext: fixtures.invalidAppContext as any
+          })
+
+        expect(init).toThrow()
+      })
+    })
+  })
+
+  describe('.get()', () => {
+    let instance
+
+    beforeEach(() => {
+      instance = new AppContext({ appContext: fixtures.validAppContext })
+    })
+
+    it('returns the value of the requested app context property', () => {
+      const result = instance.get('appVersion')
+      expect(result).toBe(fixtures.validAppContext.appVersion)
+    })
+  })
+
+  describe('.set()', () => {
+    let instance
+
+    beforeEach(() => {
+      instance = new AppContext()
+    })
+
+    it('sets the value of the specified property', () => {
+      instance.set('appVersion', 'v12')
+      expect(instance.data.appVersion).toBe('v12')
+    })
+
+    it('throws if the given value is invalid', () => {
+      expect(() => instance.set('conceptId', 123)).toThrow()
+    })
+  })
+
+  describe('.getAll()', () => {
+    let instance
+
+    beforeEach(() => {
+      instance = new AppContext({ appContext: fixtures.validAppContext })
+    })
+
+    it('returns a clone of the app context data', () => {
+      const result = instance.getAll()
+      expect(result).not.toBe(instance.data)
+    })
+
+    it('freezes the app context data clone', () => {
+      const result = instance.getAll()
+      expect(Object.isFrozen(result)).toBe(true)
+    })
+  })
+})

package/src/__test__/__fixtures__/contextData.ts

@@ -0,0 +1,18 @@
+export const validAppContext = Object.freeze({
+  appName: 'article',
+  appVersion: '882797258625531f20d604f6441ef8cfcb2d772b',
+  edition: 'uk',
+  product: 'next',
+  abTestState: 'subscriberCohort:on,premiumCohort:on,topicTracker_UIDemo:100-percent',
+  contentId: 'c5935758-7730-11e9-bbad-7c18c0ea0201',
+  contentType: 'article',
+  conceptId: 'c5935738-7730-11e9-bbad-7c18c0ea8201',
+  conceptType: 'http://www.ft.com/ontology/Location',
+  isProduction: true,
+  publishReference: 'tid_17wmwszvk3'
+})
+
+export const invalidAppContext = {
+  ...validAppContext,
+  isProduction: 'yes'
+}

package/src/__test__/filterEmptyData.spec.ts

@@ -0,0 +1,32 @@
+import subject from '../filterEmptyData'
+
+const fixture = Object.freeze({
+  appName: 'article',
+  abTest: ' ',
+  appVersion: null,
+  isProduction: false
+})
+
+describe('dotcom-server-app-context/src/filterEmptyData', () => {
+  it('returns a new object', () => {
+    const result = subject(fixture)
+    expect(result).not.toBe(fixture)
+  })
+
+  it('removes null values', () => {
+    const result = subject(fixture)
+    expect(result).not.toHaveProperty('appVersion')
+  })
+
+  it('removes empty string values', () => {
+    const result = subject(fixture)
+    expect(result).not.toHaveProperty('abTest')
+  })
+
+  it('copies all defined values', () => {
+    const result = subject(fixture)
+
+    expect(result).toHaveProperty('appName', 'article')
+    expect(result).toHaveProperty('isProduction', false)
+  })
+})

package/src/__test__/validate.spec.ts

@@ -0,0 +1,20 @@
+import subject from '../validate'
+
+describe('dotcom-server-app-context/src/validate', () => {
+  it('returns true when given a valid property/value', () => {
+    expect(subject('isProduction', true)).toBe(true)
+  })
+
+  it('throws an error when given an invalid property/value', () => {
+    expect(() => subject('isProduction', 'yes')).toThrow(
+      'Validation error: data.isProduction should be boolean'
+    )
+  })
+
+  it('throws an error when given an unknown property/value', () => {
+    expect(() => subject('thisProperty', 'isNotInTheSchema')).toThrow(
+      'Validation error: data should NOT have additional properties, received "isNotInTheSchema"' +
+        '\nIf you want to share application specific data with the client, consider using @financial-times/dotcom-ui-data-embed.'
+    )
+  })
+})

package/src/filterEmptyData.ts

@@ -0,0 +1,19 @@
+const isEmptyString = (value) => typeof value === 'string' && value.trim().length === 0
+
+const isDefined = (value) => value !== undefined && value !== null
+
+type AnyObject = {
+  [key: string]: any
+}
+
+export default function filterEmptyProperties(properties: AnyObject): AnyObject {
+  const result = {}
+
+  for (const [key, value] of Object.entries(properties)) {
+    if (isDefined(value) && !isEmptyString(value)) {
+      result[key] = value
+    }
+  }
+
+  return result
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './AppContext'
+export type { TAppContext } from './types'

package/src/schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "FT App Context Schema",
+  "properties": {
+    "abTestState": {
+      "type": "string",
+      "description": "The A/B test flags data as a comma delimited string",
+      "examples": ["subscriberCohort:on,premiumCohort:on,nonUSACohort:on"],
+      "pattern": "^,*([0-9A-Za-z-_]+:[0-9A-Za-z-_]+,*)+$"
+    },
+    "appName": {
+      "type": "string",
+      "description": "The name of the application",
+      "examples": ["front-page", "stream-page", "article-page"],
+      "pattern": "^.+$"
+    },
+    "appVersion": {
+      "type": "string",
+      "description": "The running version of the app (usually a Git commit hash)",
+      "examples": ["882797258625531f20d604f6441ef8cfcb2d772b"],
+      "pattern": "^.+$"
+    },
+    "conceptId": {
+      "type": "string",
+      "description": "The UUID of the concept on the current page",
+      "examples": ["c5935758-7730-11e9-bbad-7c18c0ea0201"],
+      "pattern": "^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$"
+    },
+    "conceptType": {
+      "type": "string",
+      "description": "The type of concept on the current page",
+      "examples": ["http://www.ft.com/ontology/product/Brand", "http://www.ft.com/ontology/Location"],
+      "pattern": "^http://www.ft.com/ontology/.+$"
+    },
+    "contentId": {
+      "type": "string",
+      "description": "The UUID of the content on the current page",
+      "examples": ["c5935758-7730-11e9-bbad-7c18c0ea0201"],
+      "pattern": "^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$"
+    },
+    "contentType": {
+      "type": "string",
+      "description": "The type or sub-type of the content on the current page",
+      "examples": ["article", "video", "audio", "podcast", "package", "live-blog"],
+      "pattern": "^(article|video|audio|podcast|package|live-blog)$"
+    },
+    "edition": {
+      "type": "string",
+      "description": "The selected FT edition",
+      "examples": ["uk", "international"],
+      "pattern": "^(uk|international)$"
+    },
+    "isProduction": {
+      "type": "boolean",
+      "description": "If the app is currently running in a production environment",
+      "default": false
+    },
+    "isUserLoggedIn": {
+      "type": "boolean",
+      "description": "If the visitor is signed in to an FT account",
+      "default": false
+    },
+    "product": {
+      "type": "string",
+      "description": "The product name",
+      "default": "next",
+      "pattern": "^.+$"
+    },
+    "publishReference": {
+      "type": "string",
+      "description": "The publish reference of the content on the current page",
+      "examples": [
+        "tid_17wmwszvk3",
+        "SYNTHETIC-REQ-MONtid_UrnYVM6Waz_carousel_1534570047",
+        "republish_-453878e5-94e5-4e52-bfba-b16b024f31f8_carousel_1577700591"
+      ],
+      "pattern": "^.+$"
+    },
+    "pageKitVersion": {
+      "type": "string",
+      "description": "The version of Page Kit powering the app",
+      "examples": ["1.0.0"],
+      "pattern": "^.+$"
+    }
+  },
+  "additionalProperties": false
+}

package/src/types.d.ts

@@ -0,0 +1,15 @@
+export interface TAppContext {
+  appName: string
+  appVersion: string
+  product: string
+  edition: string
+  abTestState: string
+  contentId?: string
+  contentType?: string
+  conceptId?: string
+  conceptType?: string
+  isProduction: boolean
+  isUserLoggedIn?: boolean
+  publishReference?: string
+  [key: string]: any
+}

package/src/validate.ts

@@ -0,0 +1,24 @@
+import Ajv from 'ajv'
+import schema from './schema.json'
+
+const ajv = new Ajv()
+
+const isValid = ajv.compile(schema)
+
+export default function validate(field: string, value): boolean {
+  const data = { [field]: value }
+
+  if (isValid(data)) {
+    return true
+  } else {
+    let errorMessage = `Validation error: ${ajv.errorsText(isValid.errors)}, received "${value}"`
+    const hasErrorsForAdditionProperties = isValid.errors.some(
+      (error) => error.keyword === 'additionalProperties'
+    )
+    if (hasErrorsForAdditionProperties) {
+      errorMessage +=
+        '\nIf you want to share application specific data with the client, consider using @financial-times/dotcom-ui-data-embed.'
+    }
+    throw Error(errorMessage)
+  }
+}