decap-cms-lib-util 2.16.0-beta.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "decap-cms-lib-util",
+  "description": "Shared utilities for Decap CMS.",
+  "version": "2.16.0-beta.0",
+  "repository": "https://github.com/decaporg/decap-cms/tree/master/packages/decap-cms-lib-util",
+  "bugs": "https://github.com/decaporg/decap-cms/issues",
+  "module": "dist/esm/index.js",
+  "main": "dist/decap-cms-lib-util.js",
+  "license": "MIT",
+  "keywords": [
+    "decap-cms"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "develop": "yarn build:esm --watch",
+    "build": "cross-env NODE_ENV=production webpack",
+    "build:esm": "cross-env NODE_ENV=esm babel src --out-dir dist/esm --ignore \"**/__tests__\" --root-mode upward --extensions \".js,.jsx,.ts,.tsx\""
+  },
+  "dependencies": {
+    "js-sha256": "^0.9.0",
+    "localforage": "^1.7.3",
+    "semaphore": "^1.1.0"
+  },
+  "peerDependencies": {
+    "immutable": "^3.7.6",
+    "lodash": "^4.17.11"
+  },
+  "gitHead": "1bdf716e5655bf088a343cd90210a2d361a9db52"
+}

package/src/API.ts

@@ -0,0 +1,220 @@
+import { asyncLock } from './asyncLock';
+import unsentRequest from './unsentRequest';
+import APIError from './APIError';
+
+import type { AsyncLock } from './asyncLock';
+
+export interface FetchError extends Error {
+  status: number;
+}
+
+interface API {
+  rateLimiter?: AsyncLock;
+  buildRequest: (req: ApiRequest) => ApiRequest | Promise<ApiRequest>;
+  requestFunction?: (req: ApiRequest) => Promise<Response>;
+}
+
+export type ApiRequestObject = {
+  url: string;
+  params?: Record<string, string | boolean | number>;
+  method?: 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'PATCH';
+  headers?: Record<string, string>;
+  body?: string | FormData;
+  cache?: 'no-store';
+};
+
+export type ApiRequest = ApiRequestObject | string;
+
+class RateLimitError extends Error {
+  resetSeconds: number;
+
+  constructor(message: string, resetSeconds: number) {
+    super(message);
+    if (resetSeconds < 0) {
+      this.resetSeconds = 1;
+    } else if (resetSeconds > 60 * 60) {
+      this.resetSeconds = 60 * 60;
+    } else {
+      this.resetSeconds = resetSeconds;
+    }
+  }
+}
+
+export async function requestWithBackoff(
+  api: API,
+  req: ApiRequest,
+  attempt = 1,
+): Promise<Response> {
+  if (api.rateLimiter) {
+    await api.rateLimiter.acquire();
+  }
+
+  try {
+    const builtRequest = await api.buildRequest(req);
+    const requestFunction = api.requestFunction || unsentRequest.performRequest;
+    const response: Response = await requestFunction(builtRequest);
+    if (response.status === 429) {
+      // GitLab/Bitbucket too many requests
+      const text = await response.text().catch(() => 'Too many requests');
+      throw new Error(text);
+    } else if (response.status === 403) {
+      // GitHub too many requests
+      const json = await response.json().catch(() => ({ message: '' }));
+      if (json.message.match('API rate limit exceeded')) {
+        const now = new Date();
+        const nextWindowInSeconds = response.headers.has('X-RateLimit-Reset')
+          ? parseInt(response.headers.get('X-RateLimit-Reset')!)
+          : now.getTime() / 1000 + 60;
+
+        throw new RateLimitError(json.message, nextWindowInSeconds);
+      }
+      response.json = () => Promise.resolve(json);
+    }
+    return response;
+  } catch (err) {
+    if (attempt > 5 || err.message === "Can't refresh access token when using implicit auth") {
+      throw err;
+    } else {
+      if (!api.rateLimiter) {
+        const timeout = err.resetSeconds || attempt * attempt;
+        console.log(
+          `Pausing requests for ${timeout} ${
+            attempt === 1 ? 'second' : 'seconds'
+          } due to fetch failures:`,
+          err.message,
+        );
+        api.rateLimiter = asyncLock();
+        api.rateLimiter.acquire();
+        setTimeout(() => {
+          api.rateLimiter?.release();
+          api.rateLimiter = undefined;
+          console.log(`Done pausing requests`);
+        }, 1000 * timeout);
+      }
+      return requestWithBackoff(api, req, attempt + 1);
+    }
+  }
+}
+
+export async function readFile(
+  id: string | null | undefined,
+  fetchContent: () => Promise<string | Blob>,
+  localForage: LocalForage,
+  isText: boolean,
+) {
+  const key = id ? (isText ? `gh.${id}` : `gh.${id}.blob`) : null;
+  const cached = key ? await localForage.getItem<string | Blob>(key) : null;
+  if (cached) {
+    return cached;
+  }
+
+  const content = await fetchContent();
+  if (key) {
+    await localForage.setItem(key, content);
+  }
+  return content;
+}
+
+export type FileMetadata = {
+  author: string;
+  updatedOn: string;
+};
+
+function getFileMetadataKey(id: string) {
+  return `gh.${id}.meta`;
+}
+
+export async function readFileMetadata(
+  id: string | null | undefined,
+  fetchMetadata: () => Promise<FileMetadata>,
+  localForage: LocalForage,
+) {
+  const key = id ? getFileMetadataKey(id) : null;
+  const cached = key && (await localForage.getItem<FileMetadata>(key));
+  if (cached) {
+    return cached;
+  }
+
+  const metadata = await fetchMetadata();
+  if (key) {
+    await localForage.setItem<FileMetadata>(key, metadata);
+  }
+  return metadata;
+}
+
+/**
+ * Keywords for inferring a status that will provide a deploy preview URL.
+ */
+const PREVIEW_CONTEXT_KEYWORDS = ['deploy'];
+
+/**
+ * Check a given status context string to determine if it provides a link to a
+ * deploy preview. Checks for an exact match against `previewContext` if given,
+ * otherwise checks for inclusion of a value from `PREVIEW_CONTEXT_KEYWORDS`.
+ */
+export function isPreviewContext(context: string, previewContext: string) {
+  if (previewContext) {
+    return context === previewContext;
+  }
+  return PREVIEW_CONTEXT_KEYWORDS.some(keyword => context.includes(keyword));
+}
+
+export enum PreviewState {
+  Other = 'other',
+  Success = 'success',
+}
+
+/**
+ * Retrieve a deploy preview URL from an array of statuses. By default, a
+ * matching status is inferred via `isPreviewContext`.
+ */
+export function getPreviewStatus(
+  statuses: {
+    context: string;
+    target_url: string;
+    state: PreviewState;
+  }[],
+  previewContext: string,
+) {
+  return statuses.find(({ context }) => {
+    return isPreviewContext(context, previewContext);
+  });
+}
+
+function getConflictingBranches(branchName: string) {
+  // for cms/posts/post-1, conflicting branches are cms/posts, cms
+  const parts = branchName.split('/');
+  parts.pop();
+
+  const conflictingBranches = parts.reduce((acc, _, index) => {
+    acc = [...acc, parts.slice(0, index + 1).join('/')];
+    return acc;
+  }, [] as string[]);
+
+  return conflictingBranches;
+}
+
+export async function throwOnConflictingBranches(
+  branchName: string,
+  getBranch: (name: string) => Promise<{ name: string }>,
+  apiName: string,
+) {
+  const possibleConflictingBranches = getConflictingBranches(branchName);
+
+  const conflictingBranches = await Promise.all(
+    possibleConflictingBranches.map(b =>
+      getBranch(b)
+        .then(b => b.name)
+        .catch(() => ''),
+    ),
+  );
+
+  const conflictingBranch = conflictingBranches.filter(Boolean)[0];
+  if (conflictingBranch) {
+    throw new APIError(
+      `Failed creating branch '${branchName}' since there is already a branch named '${conflictingBranch}'. Please delete the '${conflictingBranch}' branch and try again`,
+      500,
+      apiName,
+    );
+  }
+}

package/src/APIError.ts

@@ -0,0 +1,17 @@
+export const API_ERROR = 'API_ERROR';
+
+export default class APIError extends Error {
+  message: string;
+  status: null | number;
+  api: string;
+  meta: {};
+
+  constructor(message: string, status: null | number, api: string, meta = {}) {
+    super(message);
+    this.message = message;
+    this.status = status;
+    this.api = api;
+    this.name = API_ERROR;
+    this.meta = meta;
+  }
+}

package/src/APIUtils.ts

@@ -0,0 +1,38 @@
+export const CMS_BRANCH_PREFIX = 'cms';
+export const DEFAULT_PR_BODY = 'Automatically generated by Decap CMS';
+export const MERGE_COMMIT_MESSAGE = 'Automatically generated. Merged on Decap CMS.';
+
+const DEFAULT_DECAP_CMS_LABEL_PREFIX = 'decap-cms/';
+
+function getLabelPrefix(labelPrefix: string) {
+  return labelPrefix || DEFAULT_DECAP_CMS_LABEL_PREFIX;
+}
+
+export function isCMSLabel(label: string, labelPrefix: string) {
+  return label.startsWith(getLabelPrefix(labelPrefix));
+}
+
+export function labelToStatus(label: string, labelPrefix: string) {
+  return label.slice(getLabelPrefix(labelPrefix).length);
+}
+
+export function statusToLabel(status: string, labelPrefix: string) {
+  return `${getLabelPrefix(labelPrefix)}${status}`;
+}
+
+export function generateContentKey(collectionName: string, slug: string) {
+  return `${collectionName}/${slug}`;
+}
+
+export function parseContentKey(contentKey: string) {
+  const index = contentKey.indexOf('/');
+  return { collection: contentKey.slice(0, index), slug: contentKey.slice(index + 1) };
+}
+
+export function contentKeyFromBranch(branch: string) {
+  return branch.slice(`${CMS_BRANCH_PREFIX}/`.length);
+}
+
+export function branchFromContentKey(contentKey: string) {
+  return `${CMS_BRANCH_PREFIX}/${contentKey}`;
+}

package/src/AccessTokenError.ts

@@ -0,0 +1,11 @@
+export const ACCESS_TOKEN_ERROR = 'ACCESS_TOKEN_ERROR';
+
+export default class AccessTokenError extends Error {
+  message: string;
+
+  constructor(message: string) {
+    super(message);
+    this.message = message;
+    this.name = ACCESS_TOKEN_ERROR;
+  }
+}

package/src/Cursor.ts

@@ -0,0 +1,178 @@
+import { fromJS, Map, Set } from 'immutable';
+
+type CursorStoreObject = {
+  actions: Set<string>;
+  data: Map<string, unknown>;
+  meta: Map<string, unknown>;
+};
+
+export type CursorStore = {
+  get<K extends keyof CursorStoreObject>(
+    key: K,
+    defaultValue?: CursorStoreObject[K],
+  ): CursorStoreObject[K];
+  getIn<V>(path: string[]): V;
+  set<K extends keyof CursorStoreObject, V extends CursorStoreObject[K]>(
+    key: K,
+    value: V,
+  ): CursorStoreObject[K];
+  setIn(path: string[], value: unknown): CursorStore;
+  hasIn(path: string[]): boolean;
+  mergeIn(path: string[], value: unknown): CursorStore;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  update: (...args: any[]) => CursorStore;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateIn: (...args: any[]) => CursorStore;
+};
+
+type ActionHandler = (action: string) => unknown;
+
+function jsToMap(obj: {}) {
+  if (obj === undefined) {
+    return Map();
+  }
+  const immutableObj = fromJS(obj);
+  if (!Map.isMap(immutableObj)) {
+    throw new Error('Object must be equivalent to a Map.');
+  }
+  return immutableObj;
+}
+
+const knownMetaKeys = Set([
+  'index',
+  'page',
+  'count',
+  'pageSize',
+  'pageCount',
+  'usingOldPaginationAPI',
+  'extension',
+  'folder',
+  'depth',
+]);
+
+function filterUnknownMetaKeys(meta: Map<string, string>) {
+  return meta.filter((_v, k) => knownMetaKeys.has(k as string));
+}
+
+/*
+  createCursorMap takes one of three signatures:
+  - () -> cursor with empty actions, data, and meta
+  - (cursorMap: <object/Map with optional actions, data, and meta keys>) -> cursor
+  - (actions: <array/List>, data: <object/Map>, meta: <optional object/Map>) -> cursor
+*/
+function createCursorStore(...args: {}[]) {
+  const { actions, data, meta } =
+    args.length === 1
+      ? jsToMap(args[0]).toObject()
+      : { actions: args[0], data: args[1], meta: args[2] };
+  return Map({
+    // actions are a Set, rather than a List, to ensure an efficient .has
+    actions: Set(actions),
+
+    // data and meta are Maps
+    data: jsToMap(data),
+    meta: jsToMap(meta).update(filterUnknownMetaKeys),
+  }) as CursorStore;
+}
+
+function hasAction(store: CursorStore, action: string) {
+  return store.hasIn(['actions', action]);
+}
+
+function getActionHandlers(store: CursorStore, handler: ActionHandler) {
+  return store
+    .get('actions', Set<string>())
+    .toMap()
+    .map(action => handler(action as string));
+}
+
+// The cursor logic is entirely functional, so this class simply
+// provides a chainable interface
+export default class Cursor {
+  store?: CursorStore;
+  actions?: Set<string>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data?: Map<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  meta?: Map<string, any>;
+
+  static create(...args: {}[]) {
+    return new Cursor(...args);
+  }
+
+  constructor(...args: {}[]) {
+    if (args[0] instanceof Cursor) {
+      return args[0] as Cursor;
+    }
+
+    this.store = createCursorStore(...args);
+    this.actions = this.store.get('actions');
+    this.data = this.store.get('data');
+    this.meta = this.store.get('meta');
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateStore(...args: any[]) {
+    return new Cursor(this.store!.update(...args));
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateInStore(...args: any[]) {
+    return new Cursor(this.store!.updateIn(...args));
+  }
+
+  hasAction(action: string) {
+    return hasAction(this.store!, action);
+  }
+  addAction(action: string) {
+    return this.updateStore('actions', (actions: Set<string>) => actions.add(action));
+  }
+  removeAction(action: string) {
+    return this.updateStore('actions', (actions: Set<string>) => actions.delete(action));
+  }
+  setActions(actions: Iterable<string>) {
+    return this.updateStore((store: CursorStore) => store.set('actions', Set<string>(actions)));
+  }
+  mergeActions(actions: Set<string>) {
+    return this.updateStore('actions', (oldActions: Set<string>) => oldActions.union(actions));
+  }
+  getActionHandlers(handler: ActionHandler) {
+    return getActionHandlers(this.store!, handler);
+  }
+
+  setData(data: {}) {
+    return new Cursor(this.store!.set('data', jsToMap(data)));
+  }
+  mergeData(data: {}) {
+    return new Cursor(this.store!.mergeIn(['data'], jsToMap(data)));
+  }
+  wrapData(data: {}) {
+    return this.updateStore('data', (oldData: Map<string, unknown>) =>
+      jsToMap(data).set('wrapped_cursor_data', oldData),
+    );
+  }
+  unwrapData() {
+    return [
+      this.store!.get('data').delete('wrapped_cursor_data'),
+      this.updateStore('data', (data: Map<string, unknown>) => data.get('wrapped_cursor_data')),
+    ] as [Map<string, unknown>, Cursor];
+  }
+  clearData() {
+    return this.updateStore('data', () => Map());
+  }
+
+  setMeta(meta: {}) {
+    return this.updateStore((store: CursorStore) => store.set('meta', jsToMap(meta)));
+  }
+  mergeMeta(meta: {}) {
+    return this.updateStore((store: CursorStore) =>
+      store.update('meta', (oldMeta: Map<string, unknown>) => oldMeta.merge(jsToMap(meta))),
+    );
+  }
+}
+
+// This is a temporary hack to allow cursors to be added to the
+// interface between backend.js and backends without modifying old
+// backends at all. This should be removed in favor of wrapping old
+// backends with a compatibility layer, as part of the backend API
+// refactor.
+export const CURSOR_COMPATIBILITY_SYMBOL = Symbol('cursor key for compatibility with old backends');

package/src/EditorialWorkflowError.ts

@@ -0,0 +1,12 @@
+export const EDITORIAL_WORKFLOW_ERROR = 'EDITORIAL_WORKFLOW_ERROR';
+
+export default class EditorialWorkflowError extends Error {
+  message: string;
+  notUnderEditorialWorkflow: boolean;
+  constructor(message: string, notUnderEditorialWorkflow: boolean) {
+    super(message);
+    this.message = message;
+    this.notUnderEditorialWorkflow = notUnderEditorialWorkflow;
+    this.name = EDITORIAL_WORKFLOW_ERROR;
+  }
+}

package/src/__tests__/api.spec.js

@@ -0,0 +1,12 @@
+import * as api from '../API';
+describe('Api', () => {
+  describe('getPreviewStatus', () => {
+    it('should return preview status on matching context', () => {
+      expect(api.getPreviewStatus([{ context: 'deploy' }])).toEqual({ context: 'deploy' });
+    });
+
+    it('should return undefined on matching context', () => {
+      expect(api.getPreviewStatus([{ context: 'other' }])).toBeUndefined();
+    });
+  });
+});

package/src/__tests__/apiUtils.spec.js

@@ -0,0 +1,74 @@
+import * as apiUtils from '../APIUtils';
+describe('APIUtils', () => {
+  describe('generateContentKey', () => {
+    it('should generate content key', () => {
+      expect(apiUtils.generateContentKey('posts', 'dir1/dir2/post-title')).toBe(
+        'posts/dir1/dir2/post-title',
+      );
+    });
+  });
+
+  describe('parseContentKey', () => {
+    it('should parse content key', () => {
+      expect(apiUtils.parseContentKey('posts/dir1/dir2/post-title')).toEqual({
+        collection: 'posts',
+        slug: 'dir1/dir2/post-title',
+      });
+    });
+  });
+
+  describe('isCMSLabel', () => {
+    it('should return true for CMS label', () => {
+      expect(apiUtils.isCMSLabel('decap-cms/draft', 'decap-cms/')).toBe(true);
+    });
+
+    it('should return false for non CMS label', () => {
+      expect(apiUtils.isCMSLabel('other/label', 'decap-cms/')).toBe(false);
+    });
+
+    it('should return true if the prefix not provided for CMS label', () => {
+      expect(apiUtils.isCMSLabel('decap-cms/draft', '')).toBe(true);
+    });
+
+    it('should return false if a different prefix provided for CMS label', () => {
+      expect(apiUtils.isCMSLabel('decap-cms/draft', 'other/')).toBe(false);
+    });
+
+    it('should return true for CMS label when undefined prefix is passed', () => {
+      expect(apiUtils.isCMSLabel('decap-cms/draft', undefined)).toBe(true);
+    });
+  });
+
+  describe('labelToStatus', () => {
+    it('should get status from label when default prefix is passed', () => {
+      expect(apiUtils.labelToStatus('decap-cms/draft', 'decap-cms/')).toBe('draft');
+    });
+
+    it('should get status from label when custom prefix is passed', () => {
+      expect(apiUtils.labelToStatus('other/draft', 'other/')).toBe('draft');
+    });
+
+    it('should get status from label when empty prefix is passed', () => {
+      expect(apiUtils.labelToStatus('decap-cms/draft', '')).toBe('draft');
+    });
+
+    it('should get status from label when undefined prefix is passed', () => {
+      expect(apiUtils.labelToStatus('decap-cms/draft', undefined)).toBe('draft');
+    });
+  });
+
+  describe('statusToLabel', () => {
+    it('should generate label from status when default prefix is passed', () => {
+      expect(apiUtils.statusToLabel('draft', 'decap-cms/')).toBe('decap-cms/draft');
+    });
+    it('should generate label from status when custom prefix is passed', () => {
+      expect(apiUtils.statusToLabel('draft', 'other/')).toBe('other/draft');
+    });
+    it('should generate label from status when empty prefix is passed', () => {
+      expect(apiUtils.statusToLabel('draft', '')).toBe('decap-cms/draft');
+    });
+    it('should generate label from status when undefined prefix is passed', () => {
+      expect(apiUtils.statusToLabel('draft', undefined)).toBe('decap-cms/draft');
+    });
+  });
+});

package/src/__tests__/asyncLock.spec.js

@@ -0,0 +1,85 @@
+import { asyncLock } from '../asyncLock';
+
+jest.useFakeTimers();
+jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+describe('asyncLock', () => {
+  it('should be able to acquire a new lock', async () => {
+    const lock = asyncLock();
+
+    const acquired = await lock.acquire();
+
+    expect(acquired).toBe(true);
+  });
+
+  it('should not be able to acquire an acquired lock', async () => {
+    const lock = asyncLock();
+    await lock.acquire();
+
+    const promise = lock.acquire();
+
+    // advance by default lock timeout
+    jest.advanceTimersByTime(15000);
+
+    const acquired = await promise;
+
+    expect(acquired).toBe(false);
+  });
+
+  it('should be able to acquire an acquired lock that was released', async () => {
+    const lock = asyncLock();
+    await lock.acquire();
+
+    const promise = lock.acquire();
+
+    // release the lock in the "future"
+    setTimeout(() => lock.release(), 100);
+
+    // advance to the time where the lock will be released
+    jest.advanceTimersByTime(100);
+
+    const acquired = await promise;
+
+    expect(acquired).toBe(true);
+  });
+
+  it('should accept a timeout for acquire', async () => {
+    const lock = asyncLock();
+    await lock.acquire();
+
+    const promise = lock.acquire(50);
+
+    /// advance by lock timeout
+    jest.advanceTimersByTime(50);
+
+    const acquired = await promise;
+
+    expect(acquired).toBe(false);
+  });
+
+  it('should be able to re-acquire a lock after a timeout', async () => {
+    const lock = asyncLock();
+    await lock.acquire();
+
+    const promise = lock.acquire();
+
+    // advance by default lock timeout
+    jest.advanceTimersByTime(15000);
+
+    let acquired = await promise;
+
+    expect(acquired).toBe(false);
+
+    acquired = await lock.acquire();
+    expect(acquired).toBe(true);
+  });
+
+  it('should suppress "leave called too many times" error', async () => {
+    const lock = asyncLock();
+
+    await expect(() => lock.release()).not.toThrow();
+
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    expect(console.warn).toHaveBeenCalledWith('leave called too many times.');
+  });
+});