@financial-times/dotcom-server-asset-loader 7.3.1 → 7.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/dotcom-server-asset-loader",
-  "version": "7.3.1",
+  "version": "7.3.3",
   "description": "",
   "main": "dist/node/index.js",
   "types": "src/index.ts",
@@ -22,7 +22,8 @@
     "npm": "7.x || 8.x"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "src/"
   ],
   "repository": {
     "type": "git",
@@ -39,4 +40,4 @@
   "devDependencies": {
     "check-engine": "^1.10.1"
   }
-}
+}

package/src/AssetLoader.ts

@@ -0,0 +1,137 @@
+import path from 'path'
+import urlJoin from 'url-join'
+import { loadFile } from './helpers/loadFile'
+import { loadManifest } from './helpers/loadManifest'
+
+export interface AssetLoaderOptions {
+  /**
+   * The name of the asset manifest file
+   * @default "manifest.json"
+   */
+  manifestFileName?: string
+
+  /**
+   * The public-facing URL for the static assets
+   */
+  publicPath?: string
+
+  /**
+   * The absolute path to the directory of static assets
+   * @default path.resolve('./public')
+   */
+  fileSystemPath?: string
+
+  /**
+   * Store files in memory when accessed
+   * @default false
+   */
+  cacheFileContents?: boolean
+
+  /**
+   * The asset manifest
+   */
+  manifest?: { [asset: string]: string }
+}
+
+const defaultOptions: AssetLoaderOptions = {
+  publicPath: '/',
+  manifestFileName: 'manifest.json',
+  fileSystemPath: path.resolve('./public'),
+  cacheFileContents: false
+}
+
+type TEntrypoint = {
+  [type: string]: string[]
+}
+
+type TEntrypoints = {
+  entrypoints?: {
+    [name: string]: TEntrypoint
+  }
+}
+
+type TFiles = {
+  [name: string]: string
+}
+
+export type TManifest = TEntrypoints & TFiles
+
+export class AssetLoader {
+  public options: AssetLoaderOptions
+  public manifest: TManifest
+
+  constructor(userOptions?: AssetLoaderOptions) {
+    this.options = { ...defaultOptions, ...userOptions }
+    this.manifest =
+      this.options.manifest ||
+      loadManifest(path.resolve(this.options.fileSystemPath, this.options.manifestFileName))
+  }
+
+  getHashedAsset(asset: string): string {
+    if (this.manifest.hasOwnProperty(asset)) {
+      return this.manifest[asset]
+    } else {
+      throw Error(`Couldn't find asset "${asset}" in manifest`)
+    }
+  }
+
+  getFileContents(asset: string): string {
+    return loadFile(this.getFileSystemPath(asset), this.options.cacheFileContents)
+  }
+
+  getFileSystemPath(asset: string): string {
+    return this.formatFileSystemPath(this.getHashedAsset(asset))
+  }
+
+  getPublicURL(asset: string): string {
+    return this.formatPublicURL(this.getHashedAsset(asset))
+  }
+
+  //
+  // File name prefix methods
+  //
+
+  formatPublicURL(hashedAsset: string): string {
+    return urlJoin(this.options.publicPath, hashedAsset)
+  }
+
+  formatFileSystemPath(hashedAsset: string): string {
+    return path.join(this.options.fileSystemPath, hashedAsset)
+  }
+
+  //
+  // Webpack entry point methods
+  //
+
+  getFilesFor(entrypoint: string): TEntrypoint {
+    if (this.manifest.entrypoints && this.manifest.entrypoints[entrypoint]) {
+      return this.manifest.entrypoints[entrypoint]
+    } else {
+      throw Error(`Couldn't find entrypoint "${entrypoint}" in manifest`)
+    }
+  }
+
+  getScriptFilesFor(entrypoint: string): string[] {
+    return this.getFilesFor(entrypoint).js || []
+  }
+
+  getStylesheetFilesFor(entrypoint: string): string[] {
+    return this.getFilesFor(entrypoint).css || []
+  }
+
+  getScriptPathsFor(entrypoint: string): string[] {
+    return this.getScriptFilesFor(entrypoint).map(this.formatFileSystemPath.bind(this))
+  }
+
+  getStylesheetPathsFor(entrypoint: string): string[] {
+    return this.getStylesheetFilesFor(entrypoint).map(this.formatFileSystemPath.bind(this))
+  }
+
+  getScriptURLsFor(entrypoint: string): string[] {
+    return this.getScriptFilesFor(entrypoint).map(this.formatPublicURL.bind(this))
+  }
+
+  getStylesheetURLsFor(entrypoint: string): string[] {
+    return this.getStylesheetFilesFor(entrypoint).map(this.formatPublicURL.bind(this))
+  }
+}

package/src/__test__/AssetLoader.spec.ts

@@ -0,0 +1,181 @@
+import { AssetLoader, AssetLoaderOptions } from '../AssetLoader'
+import manifest from './__fixtures__/manifest.json'
+
+jest.mock('../helpers/loadManifest', () => {
+  return {
+    loadManifest: jest.fn(() => manifest)
+  }
+})
+
+jest.mock('../helpers/loadFile', () => {
+  return {
+    loadFile: jest.fn(() => {
+      return 'FILE CONTENTS'
+    })
+  }
+})
+
+function createAssetLoader(options?: AssetLoaderOptions) {
+  return new AssetLoader(options)
+}
+
+describe('dotcom-server-asset-loader/src/AssetLoader', () => {
+  let loader
+
+  beforeEach(() => {
+    loader = createAssetLoader({
+      publicPath: '/public/assets/',
+      fileSystemPath: '/internal/path/to/assets'
+    })
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  describe('constructor', () => {
+    it('uses the supplied manifest instead of looking it up', () => {
+      const manifest = { foo: 'bar' }
+      const loader = createAssetLoader({ manifest })
+      const result = loader.getHashedAsset('foo')
+      expect(result).toBe(manifest.foo)
+    })
+  })
+
+  describe('.getHashedAsset()', () => {
+    it('returns the hashed name from a manifest', () => {
+      const result = loader.getHashedAsset('styles.css')
+      expect(result).toEqual('styles.12345.bundle.css')
+    })
+
+    it("errors if the file can't be found in the manifest", () => {
+      expect(() => {
+        loader.getHashedAsset('test')
+      }).toThrow(Error('Couldn\'t find asset "test" in manifest'))
+    })
+  })
+
+  describe('.getFileSystemPath()', () => {
+    it('returns the file system path for the requested file', () => {
+      const result = loader.getFileSystemPath('styles.css')
+      expect(result).toEqual('/internal/path/to/assets/styles.12345.bundle.css')
+    })
+  })
+
+  describe('.getPublicURL()', () => {
+    const tests = [
+      { expected: '/styles.12345.bundle.css' },
+      { publicPath: '', expected: 'styles.12345.bundle.css' },
+      { publicPath: '/', expected: '/styles.12345.bundle.css' },
+      { publicPath: '/lib', expected: '/lib/styles.12345.bundle.css' },
+      { publicPath: '/lib/', expected: '/lib/styles.12345.bundle.css' },
+      { publicPath: '../', expected: '../styles.12345.bundle.css' }
+    ]
+
+    tests.forEach(({ publicPath, expected }) => {
+      it(`publicPath: ${publicPath}`, () => {
+        const loader = typeof publicPath === 'undefined' ? new AssetLoader() : new AssetLoader({ publicPath })
+        const result = loader.getPublicURL('styles.css')
+        expect(result).toEqual(expected)
+      })
+    })
+  })
+
+  describe('.getFileContents()', () => {
+    it('returns the file contents for the requested file', () => {
+      const result = loader.getFileContents('styles.css')
+      expect(result).toEqual('FILE CONTENTS')
+    })
+  })
+
+  describe('.getFilesFor()', () => {
+    it('returns all file types', () => {
+      const result = loader.getFilesFor('main')
+
+      expect(Object.keys(result)).toEqual(['js', 'css'])
+      expect(result.js).toEqual(expect.any(Array))
+      expect(result.css).toEqual(expect.any(Array))
+    })
+
+    it('throws if the entry point cannot be found', () => {
+      expect(() => loader.getFilesFor('third')).toThrow()
+    })
+  })
+
+  describe('.getScriptFilesFor()', () => {
+    it('returns an array', () => {
+      const result = loader.getScriptFilesFor('main')
+      expect(result).toEqual(expect.any(Array))
+    })
+
+    it('returns an array of JS files', () => {
+      const result = loader.getScriptFilesFor('main')
+
+      expect(result.length).toBe(3)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/\.js$/)
+      })
+    })
+  })
+
+  describe('.getStylesheetFilesFor()', () => {
+    it('returns an array of CSS files', () => {
+      const result = loader.getStylesheetFilesFor('main')
+
+      expect(result.length).toBe(2)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/\.css$/)
+      })
+    })
+  })
+
+  describe('.getScriptPathsFor()', () => {
+    it('returns an array of JS file paths', () => {
+      const result = loader.getScriptPathsFor('main')
+
+      expect(result.length).toBe(3)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/^\/internal\/path\/to\/assets\/.+\.js$/)
+      })
+    })
+  })
+
+  describe('.getStylesheetPathsFor()', () => {
+    it('returns an array of CSS file paths', () => {
+      const result = loader.getStylesheetPathsFor('main')
+
+      expect(result.length).toBe(2)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/^\/internal\/path\/to\/assets\/.+\.css$/)
+      })
+    })
+  })
+
+  describe('.getScriptURLsFor()', () => {
+    it('returns an array of JS file URLs', () => {
+      const result = loader.getScriptURLsFor('main')
+
+      expect(result.length).toBe(3)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/^\/public\/assets\/.+\.js$/)
+      })
+    })
+  })
+
+  describe('.getStylesheetURLsFor()', () => {
+    it('returns an array of CSS file URLs', () => {
+      const result = loader.getStylesheetURLsFor('main')
+
+      expect(result.length).toBe(2)
+
+      result.forEach((item) => {
+        expect(item).toMatch(/^\/public\/assets\/.+\.css$/)
+      })
+    })
+  })
+})

package/src/__test__/__fixtures__/manifest.json

@@ -0,0 +1,18 @@
+{
+  "styles.css": "styles.12345.bundle.css",
+  "main.js": "main.12345.bundle.js",
+  "secondary.js": "secondary.12345.bundle.js",
+  "vendor.foo.js": "vendor.foo.12345.bundle.js",
+  "vendor.bar.js": "vendor.bar.12345.bundle.js",
+  "vendor.baz.js": "vendor.baz.12345.bundle.js",
+  "runtime.js": "runtime.bundle.js",
+  "entrypoints": {
+    "main": {
+      "js": ["vendor.foo.12345.bundle.js", "vendor.bar.12345.bundle.js", "main.12345.bundle.js"],
+      "css": ["styles.12345.bundle.css", "lazyload.12345.bundle.css"]
+    },
+    "secondary": {
+      "js": ["vendor.foo.12345.bundle.js", "vendor.baz.12345.bundle.js", "secondary.12345.bundle.js"]
+    }
+  }
+}

package/src/helpers/loadFile.ts

@@ -0,0 +1,20 @@
+import fs from 'fs'
+
+// Avoid hitting the disk each time a file is requested and instead
+// hold the file contents in memory for the lifecycle of the app
+const store = new Map()
+
+export function loadFile(fullPath: string, cache: boolean = false): string {
+  if (store.has(fullPath)) {
+    return store.get(fullPath)
+  } else {
+    const fileAsBuffer = fs.readFileSync(fullPath)
+    const fileAsString = String(fileAsBuffer)
+
+    if (cache) {
+      store.set(fullPath, fileAsString)
+    }
+
+    return fileAsString
+  }
+}

package/src/helpers/loadManifest.ts

@@ -0,0 +1,6 @@
+import { loadFile } from './loadFile'
+
+export function loadManifest(filePath: string) {
+  const manifest = loadFile(filePath)
+  return JSON.parse(manifest)
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './AssetLoader'