@difizen/libro-common 0.0.2-alpha.0

package/src/iter.ts

@@ -0,0 +1,199 @@
+/**
+ * An object which can produce an iterator over its values.
+ */
+export interface IIterable<T> {
+  /**
+   * Get an iterator over the object's values.
+   *
+   * @returns An iterator which yields the object's values.
+   *
+   * #### Notes
+   * Depending on the iterable, the returned iterator may or may not be
+   * a new object. A collection or other container-like object should
+   * typically return a new iterator, while an iterator itself should
+   * normally return `this`.
+   */
+  iter: () => IIterator<T>;
+}
+
+/**
+ * An object which traverses a collection of values.
+ *
+ * #### Notes
+ * An `IIterator` is itself an `IIterable`. Most implementations of
+ * `IIterator` should simply return `this` from the `iter()` method.
+ */
+export interface IIterator<T> extends IIterable<T> {
+  /**
+   * Create an independent clone of the iterator.
+   *
+   * @returns A new independent clone of the iterator.
+   *
+   * #### Notes
+   * The cloned iterator can be consumed independently of the current
+   * iterator. In essence, it is a copy of the iterator value stream
+   * which starts at the current location.
+   *
+   * This can be useful for lookahead and stream duplication.
+   */
+  clone: () => IIterator<T>;
+
+  /**
+   * Get the next value from the iterator.
+   *
+   * @returns The next value from the iterator, or `undefined`.
+   *
+   * #### Notes
+   * The `undefined` value is used to signal the end of iteration and
+   * should therefore not be used as a value in a collection.
+   *
+   * The use of the `undefined` sentinel is an explicit design choice
+   * which favors performance over purity. The ES6 iterator design of
+   * returning a `{ value, done }` pair is suboptimal, as it requires
+   * an object allocation on each iteration; and an `isDone()` method
+   * would increase implementation and runtime complexity.
+   */
+  next: () => T | undefined;
+}
+
+/**
+ * A type alias for an iterable or builtin array-like object.
+ */
+export type IterableOrArrayLike<T> = IIterable<T> | ArrayLike<T>;
+
+/**
+ * An iterator for an array-like object.
+ *
+ * #### Notes
+ * This iterator can be used for any builtin JS array-like object.
+ */
+export class ArrayIterator<T> implements IIterator<T> {
+  /**
+   * Construct a new array iterator.
+   *
+   * @param source - The array-like object of interest.
+   */
+  constructor(source: ArrayLike<T>) {
+    this._source = source;
+  }
+
+  /**
+   * Get an iterator over the object's values.
+   *
+   * @returns An iterator which yields the object's values.
+   */
+  iter(): IIterator<T> {
+    return this;
+  }
+
+  /**
+   * Create an independent clone of the iterator.
+   *
+   * @returns A new independent clone of the iterator.
+   */
+  clone(): IIterator<T> {
+    const result = new ArrayIterator<T>(this._source);
+    result._index = this._index;
+    return result;
+  }
+
+  /**
+   * Get the next value from the iterator.
+   *
+   * @returns The next value from the iterator, or `undefined`.
+   */
+  next(): T | undefined {
+    if (this._index >= this._source.length) {
+      return undefined;
+    }
+    return this._source[this._index++];
+  }
+
+  private _index = 0;
+  private _source: ArrayLike<T>;
+}
+
+/**
+ * Create an iterator for an iterable object.
+ *
+ * @param object - The iterable or array-like object of interest.
+ *
+ * @returns A new iterator for the given object.
+ *
+ * #### Notes
+ * This function allows iteration algorithms to operate on user-defined
+ * iterable types and builtin array-like objects in a uniform fashion.
+ */
+export function iter<T>(object: IterableOrArrayLike<T>): IIterator<T> {
+  let it: IIterator<T>;
+  if (typeof (object as any).iter === 'function') {
+    it = (object as IIterable<T>).iter();
+  } else {
+    it = new ArrayIterator<T>(object as ArrayLike<T>);
+  }
+  return it;
+}
+
+/**
+ * Invoke a function for each value in an iterable.
+ *
+ * @param object - The iterable or array-like object of interest.
+ *
+ * @param fn - The callback function to invoke for each value.
+ *
+ * #### Notes
+ * Iteration can be terminated early by returning `false` from the
+ * callback function.
+ *
+ * #### Complexity
+ * Linear.
+ *
+ * #### Example
+ * ```typescript
+ *
+ * let data = [5, 7, 0, -2, 9];
+ *
+ * each(data, value => { console.log(value); });
+ * ```
+ */
+export function each<T>(
+  object: IterableOrArrayLike<T>,
+  fn: (value: T, index: number) => boolean | void,
+): void {
+  let index = 0;
+  const it = iter(object);
+  let value: T | undefined;
+  while ((value = it.next()) !== undefined) {
+    if (fn(value, index++) === false) {
+      return;
+    }
+  }
+}
+
+/**
+ * Create an array from an iterable of values.
+ *
+ * @param object - The iterable or array-like object of interest.
+ *
+ * @returns A new array of values from the given object.
+ *
+ * #### Example
+ * ```typescript
+ *
+ * let data = [1, 2, 3, 4, 5, 6];
+ *
+ * let stream = iter(data);
+ *
+ * toArray(stream);  // [1, 2, 3, 4, 5, 6];
+ * ```
+ */
+export function toArray<T>(object: IterableOrArrayLike<T>): T[] {
+  let index = 0;
+  const result: T[] = [];
+  const it = iter(object);
+  let value: T | undefined;
+  while ((value = it.next()) !== undefined) {
+    result[index++] = value;
+  }
+  return result;
+}

package/src/json.ts

@@ -0,0 +1,321 @@
+/**
+ * A type alias for a JSON primitive.
+ */
+export type JSONPrimitive = boolean | number | string | null;
+
+/**
+ * A type alias for a JSON value.
+ */
+export type JSONValue = JSONPrimitive | { [key: string]: JSONValue } | JSONValue[];
+
+/**
+ * A type definition for a JSON object.
+ */
+export type JSONObject = Record<string, JSONValue>;
+
+/**
+ * A type definition for a JSON array.
+ */
+export type JSONArray = JSONValue[];
+
+/**
+ * A type definition for a readonly JSON object.
+ */
+export type ReadonlyJSONObject = Readonly<Record<string, ReadonlyJSONValue>>;
+
+/**
+ * A type definition for a readonly JSON array.
+ */
+export type ReadonlyJSONArray = readonly ReadonlyJSONValue[];
+
+/**
+ * A type alias for a readonly JSON value.
+ */
+export type ReadonlyJSONValue =
+  | JSONPrimitive
+  | Readonly<{ [key: string]: ReadonlyJSONValue }>
+  | readonly ReadonlyJSONValue[];
+
+/**
+ * A type alias for a partial JSON value.
+ *
+ * Note: Partial here means that JSON object attributes can be `undefined`.
+ */
+export type PartialJSONValue =
+  | JSONPrimitive
+  | Partial<{ [key: string]: PartialJSONValue }>
+  | PartialJSONValue[];
+
+/**
+ * A type definition for a partial JSON array.
+ *
+ * Note: Partial here means that JSON object attributes can be `undefined`.
+ */
+export type PartialJSONArray = PartialJSONValue[];
+
+/**
+ * A type definition for a partial JSON object.
+ *
+ * Note: Partial here means that the JSON object attributes can be `undefined`.
+ */
+export type PartialJSONObject = Record<string, PartialJSONValue | undefined>;
+
+/**
+ * A type definition for a readonly partial JSON object.
+ *
+ * Note: Partial here means that JSON object attributes can be `undefined`.
+ */
+export type ReadonlyPartialJSONObject = Readonly<
+  Record<string, ReadonlyPartialJSONValue | undefined>
+>;
+
+/**
+ * A type definition for a readonly partial JSON array.
+ *
+ * Note: Partial here means that JSON object attributes can be `undefined`.
+ */
+export type ReadonlyPartialJSONArray = readonly ReadonlyPartialJSONValue[];
+
+/**
+ * A type alias for a readonly partial JSON value.
+ *
+ * Note: Partial here means that JSON object attributes can be `undefined`.
+ */
+export type ReadonlyPartialJSONValue =
+  | JSONPrimitive
+  | { readonly [key: string]: ReadonlyPartialJSONValue | undefined }
+  | readonly ReadonlyPartialJSONValue[];
+
+/**
+ * A shared frozen empty JSONObject
+ */
+export const emptyObject = Object.freeze({}) as ReadonlyJSONObject;
+
+/**
+ * A shared frozen empty JSONArray
+ */
+export const emptyArray = Object.freeze([]) as ReadonlyJSONArray;
+
+/**
+ * Test whether a JSON value is a primitive.
+ *
+ * @param value - The JSON value of interest.
+ *
+ * @returns `true` if the value is a primitive,`false` otherwise.
+ */
+export function isPrimitive(value: ReadonlyPartialJSONValue): value is JSONPrimitive {
+  return (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'number' ||
+    typeof value === 'string'
+  );
+}
+
+/**
+ * Test whether a JSON value is an array.
+ *
+ * @param value - The JSON value of interest.
+ *
+ * @returns `true` if the value is a an array, `false` otherwise.
+ */
+export function isArray(value: JSONValue): value is JSONArray;
+// export function isArray(value: ReadonlyJSONValue): value is ReadonlyJSONArray;
+export function isArray(value: PartialJSONValue): value is PartialJSONArray;
+export function isArray(
+  value: ReadonlyPartialJSONValue,
+): value is ReadonlyPartialJSONArray;
+export function isArray(value: ReadonlyPartialJSONValue): boolean {
+  return Array.isArray(value);
+}
+
+/**
+ * Test whether a JSON value is an object.
+ *
+ * @param value - The JSON value of interest.
+ *
+ * @returns `true` if the value is a an object, `false` otherwise.
+ */
+export function isObject(value: JSONValue): value is JSONObject;
+// export function isObject(value: ReadonlyJSONValue): value is ReadonlyJSONObject;
+export function isObject(value: PartialJSONValue): value is PartialJSONObject;
+// export function isObject(value: ReadonlyPartialJSONValue): value is ReadonlyPartialJSONObject;
+export function isObject(value: ReadonlyPartialJSONValue): boolean {
+  return !isPrimitive(value) && !isArray(value);
+}
+
+/**
+ * Compare two JSON values for deep equality.
+ *
+ * @param first - The first JSON value of interest.
+ *
+ * @param second - The second JSON value of interest.
+ *
+ * @returns `true` if the values are equivalent, `false` otherwise.
+ */
+export function deepEqual(
+  first: ReadonlyPartialJSONValue,
+  second: ReadonlyPartialJSONValue,
+): boolean {
+  // Check referential and primitive equality first.
+  if (first === second) {
+    return true;
+  }
+
+  // If one is a primitive, the `===` check ruled out the other.
+  if (isPrimitive(first) || isPrimitive(second)) {
+    return false;
+  }
+
+  // Test whether they are arrays.
+  const a1 = isArray(first);
+  const a2 = isArray(second);
+
+  // Bail if the types are different.
+  if (a1 !== a2) {
+    return false;
+  }
+
+  // If they are both arrays, compare them.
+  if (a1 && a2) {
+    return deepArrayEqual(
+      first as ReadonlyPartialJSONArray,
+      second as ReadonlyPartialJSONArray,
+    );
+  }
+
+  // At this point, they must both be objects.
+  return deepObjectEqual(
+    first as ReadonlyPartialJSONObject,
+    second as ReadonlyPartialJSONObject,
+  );
+}
+
+/**
+ * Create a deep copy of a JSON value.
+ *
+ * @param value - The JSON value to copy.
+ *
+ * @returns A deep copy of the given JSON value.
+ */
+export function deepCopy<T extends ReadonlyPartialJSONValue>(value: T): T {
+  // Do nothing for primitive values.
+  if (isPrimitive(value)) {
+    return value;
+  }
+
+  // Deep copy an array.
+  if (isArray(value)) {
+    return deepArrayCopy(value);
+  }
+
+  // Deep copy an object.
+  return deepObjectCopy(value);
+}
+
+/**
+ * Compare two JSON arrays for deep equality.
+ */
+function deepArrayEqual(
+  first: ReadonlyPartialJSONArray,
+  second: ReadonlyPartialJSONArray,
+): boolean {
+  // Check referential equality first.
+  if (first === second) {
+    return true;
+  }
+
+  // Test the arrays for equal length.
+  if (first.length !== second.length) {
+    return false;
+  }
+
+  // Compare the values for equality.
+  for (let i = 0, n = first.length; i < n; ++i) {
+    if (!deepEqual(first[i], second[i])) {
+      return false;
+    }
+  }
+
+  // At this point, the arrays are equal.
+  return true;
+}
+
+/**
+ * Compare two JSON objects for deep equality.
+ */
+function deepObjectEqual(
+  first: ReadonlyPartialJSONObject,
+  second: ReadonlyPartialJSONObject,
+): boolean {
+  // Check referential equality first.
+  if (first === second) {
+    return true;
+  }
+
+  // Check for the first object's keys in the second object.
+  for (const key in first) {
+    if (first[key] !== undefined && !(key in second)) {
+      return false;
+    }
+  }
+
+  // Check for the second object's keys in the first object.
+  for (const key in second) {
+    if (second[key] !== undefined && !(key in first)) {
+      return false;
+    }
+  }
+
+  // Compare the values for equality.
+  for (const key in first) {
+    // Get the values.
+    const firstValue = first[key];
+    const secondValue = second[key];
+
+    // If both are undefined, ignore the key.
+    if (firstValue === undefined && secondValue === undefined) {
+      continue;
+    }
+
+    // If only one value is undefined, the objects are not equal.
+    if (firstValue === undefined || secondValue === undefined) {
+      return false;
+    }
+
+    // Compare the values.
+    if (!deepEqual(firstValue, secondValue)) {
+      return false;
+    }
+  }
+
+  // At this point, the objects are equal.
+  return true;
+}
+
+/**
+ * Create a deep copy of a JSON array.
+ */
+function deepArrayCopy(value: any): any {
+  const result = new Array<any>(value.length);
+  for (let i = 0, n = value.length; i < n; ++i) {
+    result[i] = deepCopy(value[i]);
+  }
+  return result;
+}
+
+/**
+ * Create a deep copy of a JSON object.
+ */
+function deepObjectCopy(value: any): any {
+  const result: any = {};
+  for (const key in value) {
+    // Ignore undefined values.
+    const subvalue = value[key];
+    if (subvalue === undefined) {
+      continue;
+    }
+    result[key] = deepCopy(subvalue);
+  }
+  return result;
+}

package/src/path.ts

@@ -0,0 +1,138 @@
+/* eslint-disable no-param-reassign */
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import { posix } from 'path-browserify';
+
+/**
+ * The namespace for path-related functions.
+ *
+ * Note that Jupyter server paths do not start with a leading slash.
+ */
+export namespace PathExt {
+  /**
+   * Join all arguments together and normalize the resulting path.
+   * Arguments must be strings. In v0.8, non-string arguments were silently ignored. In v0.10 and up, an exception is thrown.
+   *
+   * @param paths - The string paths to join.
+   */
+  export function join(...paths: string[]): string {
+    const path = posix.join(...paths);
+    return path === '.' ? '' : removeSlash(path);
+  }
+
+  /**
+   * Return the last portion of a path. Similar to the Unix basename command.
+   * Often used to extract the file name from a fully qualified path.
+   *
+   * @param path - The path to evaluate.
+   *
+   * @param ext - An extension to remove from the result.
+   */
+  export function basename(path: string, ext?: string): string {
+    return posix.basename(path, ext);
+  }
+
+  /**
+   * Get the directory name of a path, similar to the Unix dirname command.
+   * When an empty path is given, returns the root path.
+   *
+   * @param path - The file path.
+   */
+  export function dirname(path: string): string {
+    const dir = removeSlash(posix.dirname(path));
+    return dir === '.' ? '' : dir;
+  }
+
+  /**
+   * Get the extension of the path.
+   *
+   * @param path - The file path.
+   *
+   * @returns the extension of the file.
+   *
+   * #### Notes
+   * The extension is the string from the last occurrence of the `.`
+   * character to end of string in the last portion of the path, inclusive.
+   * If there is no `.` in the last portion of the path, or if the first
+   * character of the basename of path [[basename]] is `.`, then an
+   * empty string is returned.
+   */
+  export function extname(path: string): string {
+    return posix.extname(path);
+  }
+
+  /**
+   * Normalize a string path, reducing '..' and '.' parts.
+   * When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
+   * When an empty path is given, returns the root path.
+   *
+   * @param path - The string path to normalize.
+   */
+  export function normalize(path: string): string {
+    if (path === '') {
+      return '';
+    }
+    return removeSlash(posix.normalize(path));
+  }
+
+  /**
+   * Resolve a sequence of paths or path segments into an absolute path.
+   * The root path in the application has no leading slash, so it is removed.
+   *
+   * @param parts - The paths to join.
+   *
+   * #### Notes
+   * The right-most parameter is considered {to}.  Other parameters are considered an array of {from}.
+   *
+   * Starting from leftmost {from} parameter, resolves {to} to an absolute path.
+   *
+   * If {to} isn't already absolute, {from} arguments are prepended in right to left order, until an absolute path is found. If after using all {from} paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the root directory.
+   */
+  export function resolve(...parts: string[]): string {
+    return removeSlash(posix.resolve(...parts));
+  }
+
+  /**
+   * Solve the relative path from {from} to {to}.
+   *
+   * @param from - The source path.
+   *
+   * @param to - The target path.
+   *
+   * #### Notes
+   * If from and to each resolve to the same path (after calling
+   * path.resolve() on each), a zero-length string is returned.
+   * If a zero-length string is passed as from or to, `/`
+   * will be used instead of the zero-length strings.
+   */
+  export function relative(from: string, to: string): string {
+    return removeSlash(posix.relative(from, to));
+  }
+
+  /**
+   * Normalize a file extension to be of the type `'.foo'`.
+   *
+   * @param extension - the file extension.
+   *
+   * #### Notes
+   * Adds a leading dot if not present and converts to lower case.
+   */
+  export function normalizeExtension(extension: string): string {
+    if (extension.length > 0 && extension.indexOf('.') !== 0) {
+      extension = `.${extension}`;
+    }
+    return extension;
+  }
+
+  /**
+   * Remove the leading slash from a path.
+   *
+   * @param path: the path from which to remove a leading slash.
+   */
+  export function removeSlash(path: string): string {
+    if (path.indexOf('/') === 0) {
+      path = path.slice(1);
+    }
+    return path;
+  }
+}

package/src/polling/index.ts

@@ -0,0 +1,2 @@
+export { Poll } from './poll.js';
+export * from './protocol.js';