packages: add initial version of version-bridge package

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2021-09-10 16:43:46 +02:00
parent c9ce2ba317
commit ee560a45f5
10 changed files with 375 additions and 0 deletions
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './lib';
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getGlobalSingleton, getOrCreateGlobalSingleton } from './globalObject';
+
+const anyGlobal = global as any;
+
+describe('getGlobalSingleton', () => {
+  beforeEach(() => {
+    delete anyGlobal['__@backstage/my-thing__'];
+  });
+
+  it('should return an existing value', () => {
+    const myThing = {};
+    const myOtherThing = {};
+
+    anyGlobal['__@backstage/my-thing__'] = myThing;
+    expect(getGlobalSingleton('my-thing')).toBe(myThing);
+    expect(getGlobalSingleton('my-thing')).toBe(myThing);
+    anyGlobal['__@backstage/my-thing__'] = myOtherThing;
+    expect(getGlobalSingleton('my-thing')).toBe(myOtherThing);
+  });
+
+  it('should throw if the value is not set', () => {
+    expect(() => getGlobalSingleton('my-thing')).toThrow(
+      'Global my-thing is not set',
+    );
+  });
+});
+
+describe('getOrCreateGlobalSingleton', () => {
+  beforeEach(() => {
+    delete anyGlobal['__@backstage/my-thing__'];
+  });
+
+  it('should return an existing value', () => {
+    const myThing = {};
+    anyGlobal['__@backstage/my-thing__'] = myThing;
+
+    expect(getOrCreateGlobalSingleton('my-thing', () => ({}))).toBe(myThing);
+    expect(getOrCreateGlobalSingleton('my-thing', () => ({}))).toBe(myThing);
+  });
+
+  it('should should create a new value', () => {
+    const myNewThing = {};
+
+    expect(anyGlobal['__@backstage/my-thing__']).toBe(undefined);
+    expect(getOrCreateGlobalSingleton('my-thing', () => myNewThing)).toBe(
+      myNewThing,
+    );
+    expect(anyGlobal['__@backstage/my-thing__']).toBe(myNewThing);
+    expect(getOrCreateGlobalSingleton('my-thing', () => ({}))).toBe(myNewThing);
+  });
+});
@@ -0,0 +1,73 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// https://github.com/zloirock/core-js/issues/86#issuecomment-115759028
+function getGlobalObject() {
+  if (typeof window !== 'undefined' && window.Math === Math) {
+    return window;
+  }
+  if (typeof self !== 'undefined' && self.Math === Math) {
+    return self;
+  }
+  // eslint-disable-next-line no-new-func
+  return Function('return this')();
+}
+
+const globalObject = getGlobalObject();
+
+const makeKey = (id: string) => `__@backstage/${id}__`;
+
+/**
+ * Used to provide a global singleton value, failing if it is already set.
+ */
+export function setGlobalSingleton(id: string, value: unknown): void {
+  const key = makeKey(id);
+  if (key in globalObject) {
+    throw new Error(`Global ${id} is already set`);
+  }
+  globalObject[key] = value;
+}
+
+/**
+ * Used to access a global singleton value, failing if it is not already set.
+ */
+export function getGlobalSingleton<T>(id: string): T {
+  const key = makeKey(id);
+  if (!(key in globalObject)) {
+    throw new Error(`Global ${id} is not set`);
+  }
+
+  return globalObject[key];
+}
+
+/**
+ * Serializes access to a global singleton value, with the first caller creating the value.
+ */
+export function getOrCreateGlobalSingleton<T>(
+  id: string,
+  supplier: () => T,
+): T {
+  const key = makeKey(id);
+
+  let value = globalObject[key];
+  if (value) {
+    return value;
+  }
+
+  value = supplier();
+  globalObject[key] = value;
+  return value;
+}
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './globalObject';
+export * from './versionedValues';
@@ -0,0 +1,66 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createContext, useContext, Context } from 'react';
+import { getGlobalSingleton, setGlobalSingleton } from './globalObject';
+
+/**
+ * The versioned value interface is a container for a set of values that
+ * can be looked up by version. It is intended to be used as a container
+ * for values that can be versioned independently of package versions.
+ */
+export type VersionedValue<Versions extends { [version: number]: any }> = {
+  atVersion<Version extends keyof Versions>(
+    version: Version,
+  ): Versions[Version] | undefined;
+};
+
+/**
+ * Creates a container for a map of versioned values that implements VersionedValue.
+ */
+export function createVersionedValueMap<
+  Versions extends { [version: number]: any },
+>(versions: Versions): VersionedValue<Versions> {
+  Object.freeze(versions);
+  return {
+    atVersion(version) {
+      return versions[version];
+    },
+  };
+}
+
+export function useVersionedContext<
+  Versions extends { [version in number]: any },
+>(key: string): VersionedValue<Versions> {
+  const versionedValue = useContext(
+    getGlobalSingleton<Context<VersionedValue<Versions>>>(key),
+  );
+  if (!versionedValue) {
+    throw new Error(`No provider available for ${key} context`);
+  }
+  return versionedValue;
+}
+
+export function createVersionedContextForTesting(key: string) {
+  return {
+    set(versions: { [version in number]: unknown }) {
+      setGlobalSingleton(key, createContext(createVersionedValueMap(versions)));
+    },
+    reset() {
+      delete (globalThis as any)[`__@backstage/${key}__`];
+    },
+  };
+}
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import '@testing-library/jest-dom';