@api-client/core 0.3.3 → 0.3.6

package/src/models/ProjectFolder.ts

@@ -0,0 +1,439 @@
+import { ProjectParent } from './ProjectParent.js';
+import { IProjectDefinitionProperty } from './ProjectDefinitionProperty.js';
+import { ProjectItem, IProjectItem } from './ProjectItem.js';
+import { ProjectRequest, Kind as ProjectRequestKind, IProjectRequest } from './ProjectRequest.js';
+import { HttpProject } from './HttpProject.js';
+import { IThing, Thing, Kind as ThingKind } from './Thing.js';
+import v4 from '../lib/uuid.js';
+
+export const Kind = 'ARC#ProjectFolder';
+export const DefaultFolderName = 'New folder';
+
+export interface IFolderAddOptions {
+  /**
+   * Optionally the position at which to add the request into the list of items.
+   */
+  index?: number;
+}
+
+export interface IFolderCloneOptions {
+  /**
+   * By default it clones the folder with all requests in it.
+   * Set this to `true` to skip copying the requests along with the folder.
+   */
+  withoutRequests?: boolean;
+  /**
+   * By default it clones the folder with all folders in it.
+   * Set this to `true` to skip copying the folders along with the folder.
+   */
+  withoutFolders?: boolean;
+  /**
+   * The target project where to put the copied folder.
+   * When the target project is not the same as the source project then the folder 
+   * is put into the project root rather than the parent folder (as it would when cloning
+   * a folder inside the same project).
+   */
+  targetProject?: HttpProject;
+  /**
+   * The **key** of the target folder.
+   * 
+   * By default it clones the folder to its parent unless the clone is attached to another project. 
+   * When the target folder is set then it places the clone under the passed target folder.
+   */
+  targetFolder?: string;
+}
+
+export interface IProjectFolder extends IProjectDefinitionProperty {
+  kind: typeof Kind;
+  /**
+   * The identifier of the folder.
+   */
+  key: string;
+  /**
+   * Folder meta
+   */
+  info: IThing;
+  /**
+   * The ordered list of HTTP requests / folders in the projects.
+   * The UI uses this to manipulate the view without changing the definitions.
+   */
+  items: IProjectItem[];
+  /**
+   * The environments defined for this project.
+   * If not set it is inherited from the parent.
+   */
+  environments?: string[];
+  /**
+   * Timestamp when the folder was last updated.
+   */
+  updated: number;
+  /**
+   * Timestamp when the folder was created.
+   */
+  created: number;
+}
+
+/**
+ * Represents a folder, a group of requests or other folders, in a folder.
+ */
+export class ProjectFolder extends ProjectParent {
+  /**
+   * The default name of the folder.
+   */
+  static get defaultName(): string {
+    return DefaultFolderName;
+  }
+
+  kind = Kind;
+  /**
+   * A reference to the top level project object.
+   */
+  project: HttpProject;
+  /**
+   * Timestamp when the folder was last updated.
+   */
+  updated = 0;
+  /**
+   * Timestamp when the folder was created.
+   */
+  created = 0;
+
+  constructor(project: HttpProject, input?: string | IProjectFolder) {
+    super();
+    this.project = project;
+    let init: IProjectFolder;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      const now: number = Date.now();
+      init = {
+        kind: Kind,
+        info: {
+          kind: ThingKind,
+          name: DefaultFolderName,
+        },
+        created: now,
+        updated: now,
+        items: [],
+        key: v4(),
+      };
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new project folder clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the project folder is not an ARC project folder.
+   */
+  new(init: IProjectFolder): void {
+    if (!ProjectFolder.isProjectFolder(init)) {
+      throw new Error(`Not an ARC project folder.`);
+    }
+    const { key = v4(), created = Date.now(), updated = Date.now(), items, environments, info } = init;
+    this.kind = Kind;
+    this.key = key;
+    this.created = created;
+    this.updated = updated;
+    if (Array.isArray(items)) {
+      this.items = items.map(i => new ProjectItem(this.project, i));
+    } else {
+      this.items = [];
+    }
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = new Thing({ kind: ThingKind, name: DefaultFolderName });
+    }
+    if (Array.isArray(environments)) {
+      this.environments = environments;
+    } else {
+      this.environments = [];
+    }
+  }
+
+  /**
+   * Checks whether the input is a definition of a project folder.
+   */
+  static isProjectFolder(input: unknown): boolean {
+    const typed = input as IProjectFolder;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IProjectFolder {
+    const result: IProjectFolder = {
+      kind: Kind,
+      info: this.info.toJSON(),
+      key: this.key,
+      created: this.created,
+      updated: this.updated,
+      items: [],
+      environments: [],
+    };
+    if (Array.isArray(this.items)) {
+      result.items = this.items.map(i => i.toJSON());
+    }
+    if (Array.isArray(this.environments)) {
+      result.environments = this.environments;
+    }
+    return result;
+  }
+
+  /**
+   * Creates a new ProjectFolder object from a name.
+   * @param project The top-most project.
+   * @param name The name to set.
+   */
+  static fromName(project: HttpProject, name = DefaultFolderName): ProjectFolder {
+    const now = Date.now();
+    const key = v4();
+    const info = new Thing({ kind: ThingKind, name });
+    const definition = new ProjectFolder(project, {
+      key,
+      created: now,
+      updated: now,
+      items: [],
+      environments: [],
+      kind: Kind,
+      info: info.toJSON(),
+    });
+    return definition;
+  }
+
+  /**
+   * Appends an instance of a folder to a project.
+   * 
+   * @param folder The folder to add to this project.
+   * @returns The added folder.
+   */
+  addFolder(folder: ProjectFolder): ProjectFolder;
+
+  /**
+   * Appends new folder to a project from a full folder schema.
+   * This is primarily used to insert a folder on the client side
+   * after a folder was created in the store.
+   * 
+   * @param folder The folder schema to add to this project.
+   * @returns The added folder.
+   */
+  addFolder(folder: IProjectFolder): ProjectFolder;
+
+  /**
+   * Appends a new folder to the project or a sub-folder.
+   * 
+   * @param name The name to set. Optional.
+   * @returns The newly inserted folder. If the folder already existed it returns its instance.
+   */
+  addFolder(name?: string): ProjectFolder;
+
+  /**
+   * Appends a new folder to the folder. It updates the project to add the request definition.
+   * @param name The name to set. Optional.
+   * @returns The key of newly inserted folder.
+   */
+  addFolder(name: string | IProjectFolder | ProjectFolder | undefined): ProjectFolder {
+    return this.project.addFolder(name as ProjectFolder, { parent: this.key });
+  }
+
+  /**
+   * Adds a request to the project or a sub-folder.
+   * 
+   * @param url The URL of the request.
+   * @param opts The request add options.
+   * @returns The inserted into the definitions request.
+   */
+  addRequest(url: string, opts?: IFolderAddOptions): ProjectRequest;
+
+  /**
+   * Adds a request to the project or a sub-folder.
+   * 
+   * @param request The request to add.
+   * @param opts The request add options.
+   * @returns The inserted into the definitions request.
+   */
+  addRequest(request: IProjectRequest | ProjectRequest, opts?: IFolderAddOptions): ProjectRequest;
+
+  /**
+   * Appends a new request to the folder. It updates the project to add the request definition.
+   * @param request The request to append to the folder.
+   * @returns The key of newly inserted request.
+   */
+  addRequest(request: IProjectRequest | ProjectRequest | string, opts: IFolderAddOptions = {}): ProjectRequest {
+    const addOptions = { parent: this.key, ...opts };
+    if (typeof request === 'string') {
+      return this.project.addRequest(request, addOptions);
+    }
+    return this.project.addRequest(request, addOptions);
+  }
+
+  /**
+   * Lists items (not the actual definitions!) that are folders.
+   */
+  listFolderItems(): ProjectItem[] {
+    const { items = [] } = this;
+    return items.filter(i => i.kind === Kind);
+  }
+
+  /**
+   * Lists items (not the actual definitions!) that are requests.
+   */
+  listRequestItems(): ProjectItem[] {
+    const { items = [] } = this;
+    return items.filter(i => i.kind === ProjectRequestKind);
+  }
+
+  /**
+   * Lists folders in this folder.
+   */
+  listFolders(): ProjectFolder[] {
+    return this.project.listFolders({ folder: this.key });
+  }
+
+  /**
+   * Lists requests in this folder.
+   */
+  listRequests(): ProjectRequest[] {
+    return this.project.listRequests(this.key);
+  }
+
+  /**
+   * The callback called when the object is attached to a parent.
+   * This is called when the object is created and inserted to a project or a folder
+   * and when the object is moved between folders.
+   */
+  attachedCallback(): void {
+    // ...
+  }
+
+  /**
+   * The callback called when the object is detached from its parent.
+   * This callback is called when the item is deleted from a folder or a project,
+   * or when the item is about to be moved to another folder.
+   */
+  detachedCallback(): void {
+    // ...
+  }
+
+  /**
+   * @returns The instance of the HttpProject or a ProjectFolder that is a closes parent of this instance.
+   */
+  getParent(): ProjectFolder | HttpProject | undefined {
+    const { project, key } = this;
+    return project.findParent(key);
+  }
+
+  /**
+   * @returns A reference to the parent folder or the top-level HTTP project.
+   */
+  getProject(): HttpProject {
+    return this.project;
+  }
+
+  /**
+   * Removes this folder from the project.
+   */
+  remove(): void {
+    this.project.removeFolder(this.key);
+  }
+
+  /**
+   * Makes a copy of this folder.
+   * By default it attaches the copied folder to the same parent.
+   * It also, by default, copies requests declared in this folder.
+   * 
+   * Use the options dictionary to control these behaviors.
+   * 
+   * @param opts Cloning options
+   */
+  clone(opts: IFolderCloneOptions = {}): ProjectFolder {
+    const { targetProject=this.project, targetFolder } = opts;
+    const copy = new ProjectFolder(targetProject, this.toJSON());
+    copy.key = v4();
+
+    const extProject = targetProject !== this.project;
+    if (extProject) {
+      if (targetFolder) {
+        const parent = targetProject.findFolder(targetFolder, { keyOnly: true });
+        if (!parent) {
+          throw new Error(`The target project does not contain the folder ${targetFolder}`);
+        }
+        parent.addFolder(copy);
+      } else {
+        targetProject.addFolder(copy);
+      }
+    } else {
+      const parent = targetFolder ? this.project.findFolder(targetFolder, { keyOnly: true }) : this.getParent();
+      if (parent) {
+        parent.addFolder(copy);
+      } else {
+        throw new Error(`Unable to locate a parent of the folder.`);
+      }
+    }
+    // removes all items. Depending on the passed option we re-add them next.
+    copy.items = [];
+
+    if (!opts.withoutRequests) {
+      this.cloneRequests(copy, this.project);
+    }
+    if (!opts.withoutFolders) {
+      this.cloneSubFolders(copy, this.project, !opts.withoutRequests);
+    }
+    return copy;
+  }
+
+  /**
+   * Clones the current requests to the target folder.
+   * 
+   * @param folder The target folder into which to put the requests. The folder has to have the target project attached to it.
+   * @param project The originating project where the definitions are stored
+   */
+  protected cloneRequests(folder: ProjectFolder, project: HttpProject): void {
+    const requests = this.items.filter(i => i.kind === ProjectRequestKind);
+    requests.forEach(r => {
+      const request = project.findRequest(r.key, { keyOnly: true });
+      if (!request) {
+        // Should we throw an error here?
+        // CONS:
+        // - It's not really related to the operation. It means there is an inconsistency in the project. That's the role of the project class.
+        // - Ignoring this would allow us to make a copy that is error free.
+        // - The error may occur in a situation when the user does not expect it (giving the nature of the error)
+        // Pros:
+        // - There's an inconsistency in the project definition that should be reported back to the UI for the user to inspect
+        return;
+      }
+      const copy = request.clone({ withoutAttach: true });
+      copy.project = folder.getProject();
+      folder.addRequest(copy);
+    });
+  }
+
+  /**
+   * Clones the sub-folders to the target folder.
+   * 
+   * @param folder The target folder into which to put the sub-folders. The folder has to have the target project attached to it.
+   * @param project The originating project where the definitions are stored
+   * @param withRequests Whether to clone requests with the folder.
+   */
+  protected cloneSubFolders(folder: ProjectFolder, project: HttpProject, withRequests = true): void {
+    const folders = this.items.filter(i => i.kind === Kind);
+    folders.forEach(f => {
+      const definition = project.findFolder(f.key, { keyOnly: true });
+      if (!definition) {
+        return;
+      }
+      const copy = new ProjectFolder(folder.getProject(), definition.toJSON());
+      copy.key = v4();
+      copy.items = [];
+      folder.addFolder(copy);
+      if (withRequests) {
+        definition.cloneRequests(copy, project);
+      }
+      definition.cloneSubFolders(copy, project, withRequests);
+    });
+  }
+}

package/src/models/ProjectItem.ts

@@ -0,0 +1,135 @@
+import { Kind as ProjectFolderKind, ProjectFolder } from './ProjectFolder.js';
+import { Kind as ProjectRequestKind, ProjectRequest } from './ProjectRequest.js';
+import { HttpProject } from './HttpProject.js';
+
+export interface IProjectItem {
+  /**
+   * The kind of the item.
+   */
+  kind: typeof ProjectFolderKind | typeof ProjectRequestKind;
+  /**
+   * The identifier in the `definitions` array of the project.
+   */
+  key: string;
+}
+
+export class ProjectItem {
+  /**
+   * The kind of the item.
+   */
+  kind: typeof ProjectFolderKind | typeof ProjectRequestKind = ProjectRequestKind;
+  /**
+   * The identifier of the object in the `definitions` array of the project.
+   */
+  key = '';
+  /**
+   * A reference to the top level project object.
+   */
+  private project: HttpProject;
+
+  /**
+   * Checks whether the input is a definition of a project item.
+   */
+  static isProjectItem(input: unknown): boolean {
+    const typed = input as IProjectItem;
+    if (!input || ![ProjectFolderKind, ProjectRequestKind].includes(typed.kind)) {
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * @return An instance that represents a request object
+   */
+  static projectRequest(project: HttpProject, key: string) : ProjectItem {
+    const item = new ProjectItem(project, {
+      kind: ProjectRequestKind,
+      key,
+    });
+    return item;
+  }
+
+  /**
+   * @return An instance that represents a folder object
+   */
+  static projectFolder(project: HttpProject, key: string) : ProjectItem {
+    const item = new ProjectItem(project, {
+      kind: ProjectFolderKind,
+      key,
+    });
+    return item;
+  }
+
+  /**
+   * @param project The top-most project.
+   * @param input The project item definition used to restore the state.
+   */
+  constructor(project: HttpProject, input: string|IProjectItem) {
+    this.project = project;
+    let init: IProjectItem;
+    if (typeof input === 'string') {
+      if (input === 'http-request') {
+        init = {
+          kind: ProjectRequestKind,
+          key: '',
+        };
+      } else if (input === 'folder') {
+        init = {
+          kind: ProjectFolderKind,
+          key: '',
+        };
+      } else {
+        init = JSON.parse(input);
+      }
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      throw new Error('Specify the type of the item.');
+    }
+    this.new(init);
+  }
+
+  /**
+   * Creates a new project item clearing anything that is so far defined.
+   * 
+   * Note, this throws an error when the project item is not an ARC project item. 
+   */
+  new(init: IProjectItem): void {
+    if (!ProjectItem.isProjectItem(init)) {
+      throw new Error(`Not an ARC project item.`);
+    }
+    const { kind, key } = init;
+    this.kind = kind;
+    this.key = key;
+  }
+
+  toJSON(): IProjectItem {
+    const result: IProjectItem = {
+      kind: this.kind,
+      key: this.key,
+    };
+    return result;
+  }
+
+  /**
+   * @returns The instance of the definition associated with this item.
+   */
+  getItem(): ProjectFolder | ProjectRequest| undefined {
+    const { project, key, kind } = this;
+    const { definitions } = project;
+    if (kind === ProjectRequestKind) {
+      return definitions.requests.find(i => i.key === key);
+    }
+    if (kind === ProjectFolderKind) {
+      return definitions.folders.find(i => i.key === key);
+    }
+  }
+
+  /**
+   * @returns The instance of the HttpProject or a ProjectFolder that is a closes parent of this item.
+   */
+  getParent(): ProjectFolder|HttpProject|undefined {
+    const { project, key } = this;
+    return project.findParent(key);
+  }
+}

package/src/models/ProjectParent.ts

@@ -0,0 +1,113 @@
+import { HttpProject } from "./HttpProject.js";
+import { ProjectFolder } from "./ProjectFolder.js";
+import { ProjectItem } from "./ProjectItem.js";
+import { Thing, Kind as ThingKind } from "./Thing.js";
+import { ProjectDefinitionProperty } from "./ProjectDefinitionProperty.js";
+import { Environment, IEnvironment } from "./Environment.js";
+import v4 from '../lib/uuid.js';
+
+/**
+ * A class that contains a common properties and methods of an `HttpProject` and
+ * a `ProjectFolder`.
+ */
+export abstract class ProjectParent implements ProjectDefinitionProperty {
+  kind: unknown;
+  key: string = '';
+  /**
+   * The environments defined for this project.
+   * If not set it is inherited from the parent.
+   */
+  environments: string[] = [];
+  /**
+   * The ordered list of HTTP requests / folders in the projects.
+   * The UI uses this to manipulate the view without changing the definitions.
+   */
+  items: ProjectItem[] = [];
+  /**
+   * The basic information about the project / folder.
+   */
+  info: Thing = new Thing({ kind: ThingKind, name: '' });
+
+  abstract attachedCallback(): void;
+
+  abstract detachedCallback(): void;
+
+  abstract getParent(): HttpProject | ProjectFolder | undefined;
+
+  abstract getProject(): HttpProject;
+
+  /**
+   * Adds an environment to the project.
+   * 
+   * @param env The definition of the environment to use to create the environment
+   * @returns The same or created environment.
+   */
+  addEnvironment(env: IEnvironment): Environment;
+
+  /**
+   * Adds an environment to the project.
+   * 
+   * @param env The instance of the environment to add
+   * @returns The same or created environment.
+   */
+  addEnvironment(env: Environment): Environment;
+
+  /**
+   * Adds an environment to the project.
+   * 
+   * @param env The name of the environment to create
+   * @returns The same or created environment.
+   */
+  addEnvironment(env: string): Environment;
+
+  /**
+   * Adds an environment to the project.
+   * @returns The same or created environment.
+   */
+  addEnvironment(env: IEnvironment | Environment | string): Environment {
+    if (!Array.isArray(this.environments)) {
+      this.environments = [];
+    }
+    let finalEnv;
+    if (env instanceof Environment) {
+      finalEnv = env;
+    } else if (typeof env === 'string') {
+      finalEnv = Environment.fromName(env);
+    } else {
+      finalEnv = new Environment(env);
+    }
+    if (!finalEnv.key) {
+      finalEnv.key = v4();
+    }
+    const project = this.getProject();
+    if (!project.definitions.environments) {
+      project.definitions.environments = [];
+    }
+    project.definitions.environments.push(finalEnv);
+    this.environments.push(finalEnv.key);
+    return finalEnv;
+  }
+
+  /**
+   * 
+   * @returns The list of environments defined in this folder.
+   */
+  getEnvironments(): Environment[] {
+    const { environments } = this;
+    if (!environments.length) {
+      return [];
+    }
+    const project = this.getProject();
+    if (!project.definitions.environments) {
+      return [];
+    }
+    const result: Environment[] = [];
+    environments.forEach((key) => {
+      const env = project.definitions.environments.find(i => i.key === key);
+      if (env) {
+        result.push(env);
+      }
+    });
+    return result;
+  }
+}