Options
All
  • Public
  • Public/Protected
  • All
Menu

@fschopp/project-planning-for-you-track

Index

Type aliases

Failure

Failure: string

Human-readable error message that can be displayed to the user.

ProgressCallback

ProgressCallback: function

Callback for progress updates.

Type declaration

    • (percentageDone: number): void
    • Parameters

      • percentageDone: number

        progress in percent; that is, a number (not necessarily integer) between 0 and 100

      Returns void

Schedule

Schedule: ScheduledIssue[]

A schedule for issues with remaining effort or wait time.

ScheduledIssue

ScheduledIssue: IssueActivity[]

Scheduled activities for an issue with remaining effort or wait time.

The same guarantees hold as for YouTrackIssue.issueActivities.

Functions

appendSchedule

  • Appends a schedule for issues with remaining effort or wait time to a project plan.

    This function does not modify any of its arguments. It returns an entirely new instance that shares no mutable data with projectPlan.

    This function merges any issue activity in projectPlan that extends into an activity in schedule for the same issue and by the same contributor.

    Parameters

    • projectPlan: ProjectPlan

      the project plan, typically containing only past issue activities

    • schedule: Schedule

      the (future) schedule for issues with remaining effort or wait time

    • divisionTimestamp: number

      Timestamp taken as end for the project plan and as beginning for the future schedule. Any project-plan activities starting at or after this timestamp, and any schedule activities ending at or before this timestamp are omitted.

    Returns ProjectPlan | Failure

    a new project plan that contains the issue activities of both projectPlan and schedule

authorizationFor

  • authorizationFor(baseUrl: string): string | undefined
  • Returns the access token for the given base URL, or undefined if there is no (unexpired) one.

    This method returns the HTTP Authorization header known due to a previous call to handlePotentialOauthRedirect(), or undefined if not known for the given URL.

    Parameters

    • baseUrl: string

      The YouTrack base URL to which relative paths of form api/... will be appended. The base URL is expected to end in a slash (/). See httpGet().

    Returns string | undefined

    value for HTTP authorization header

getMinutesPerWorkWeek

  • getMinutesPerWorkWeek(baseUrl: string): Promise<number>
  • Retrieves and returns the number of minutes in a work week, as configured in YouTrack.

    Parameters

    • baseUrl: string

      The YouTrack base URL. See also httpGet().

    Returns Promise<number>

    A promise that in case of success will be fulfilled with a the number of minutes. In case of any failure, it will be rejected with a Failure.

goToOauthPage

  • goToOauthPage<T>(youTrackBaseUrl: string, hubUrl: string, serviceId: string, appState: T, redirectUrl?: string): void
  • Navigates the current window to the Jetbrains Hub OAuth2 page.

    Once successfully logged in, the OAuth2 page will redirect the browser to the given redirectUrl. To be able to seamlessly proceed where the user left off, the current application state needs to be preserved. This method stores the given application state appState in the session storage. The rationale is:

    1. The application state could be larger than what one would reasonably encode in the redirect URL (which is another possibility of preserving the state).
    2. The application state does not leak to a third party.

    Nonetheless, users of this method should be aware of the limitations of using the session storage as well. MDN has some additional information on this topic.

    Type parameters

    • T

      type of the application state

    Parameters

    • youTrackBaseUrl: string

      The YouTrack base URL to which relative paths of form api/... will be appended. The base URL is expected to end in a slash (/). See httpGet().

    • hubUrl: string

      Hub URL to which a relative path like api/rest/oauth2/auth will be appended. The hub URL is expected to end in a slash (/). Note that the Hub URL is distinct from the YouTrack base URL.

    • serviceId: string

      Identification of the particular YouTrack installation. See the YouTrack manual.

    • appState: T

      State that will be stored in session storage and later returned by handlePotentialOauthRedirect(). The value passed as argument needs to be serializable with {@link JSON.stringify}().

    • Default value redirectUrl: string = window.location.href

      The URL that YouTrack will redirect back to after authorization. In order to not expose more data than necessary to the YouTrack server, the url will be stripped from its hash, username/password, and search query (if any). If state needs to be preserved, the appState argument should be used.

    Returns void

groupByIntervalAndWaitStatus

  • Returns the given issue activities grouped by interval and wait status.

    Every point in time is represented by at most two MultiAssigneeIssueActivity elements in the returned array; one for all assignees that are not waiting, and one for all that are. Each MultiAssigneeIssueActivity element has maximum length. In other words, no two MultiAssigneeIssueActivity elements could be merged into one.

    This function can be thought to work as follows: It first separates the activities according to wait status. Then, for both groups: It projects all start and end timestamps of the given activities onto a single timeline. It then iterates over these timestamps, and whenever the set of assignees changes:

    1. The current MultiAssigneeIssueActivity (if any) is ended.
    2. A new MultiAssigneeIssueActivity is added if the new set of assignees is non-empty. As last step, the non-waiting and waiting activities are merged (and sorted).

    Note that all functions in this package that return arrays of IssueActivity guarantee a “normalized” form. See, for instance, YouTrackIssue.issueActivities. With these extra guarantees, no activities in the array return by this function ever overlap.

    This function treats activities with empty IssueActivity.assignee in the same way as all other activities. That is, within this function, the empty string is a valid assignee name.

    Parameters

    • activities: IssueActivity[]

      The issue activities. The array does not have to be “normalized.”

    Returns MultiAssigneeIssueActivity[]

    The array of issue activities grouped by interval and wait status. The array will be sorted by the start and then by the isWaiting properties. The MultiAssigneeIssueActivity.assignees property of each element is guaranteed to be sorted, too.

handlePotentialOauthRedirect

  • handlePotentialOauthRedirect<T>(): T | undefined
  • Parses window.location.href to determine whether the URL stems from a YouTrack OAuth2 redirect, and returns the restored application state if so.

    This method is meant to be called when the page is loaded. If the current URL contains a hash that is the result of an OAuth2 redirect, any URL component except domain and path (such as search query or hash) will be removed. Note that window.location will be updated with window.history.replaceState().

    The application state will be restored from session storage. Unfortunately, some browsers are known to have bugs that cause unexpected results if sessionStorage is accessed “too early,” relative to the page load in the browser. This applies at least to Safari 12.1.1 and older versions of Firefox. (Recent versions of Chrome and Firefox appear to work just fine.) It is advisable to delay calling this method (for instance, with setTimeout()) when targeting browsers that are known to be problematic.

    Finally, this function keeps a record of the YouTrack authorization, making it available via authorizationFor().

    Type parameters

    • T

      type of the application state

    Returns T | undefined

    object containing the application state or undefined if the current location is not the result of a YouTrack OAuth2 redirect

httpGet

  • httpGet<T>(baseUrl: string, resourcePath: string, queryParams?: object): Promise<T>
  • Returns a promise that will be fulfilled with the result of an HTTP GET request to a YouTrack REST resource.

    This method sets the HTTP Authorization header if it is known due to a previous call to handlePotentialOauthRedirect(). If no authorization is available, this method rejects the promise immediately.

    Type parameters

    • T

      the type of the response by YouTrack (after parsing the JSON)

    Parameters

    • baseUrl: string

      The YouTrack base URL to which relative paths of form api/... will be appended. The base URL is expected to end in a slash (/). For an InCloud instance without a custom domain, this is of form https://<name>.myjetbrains.com/youtrack/.

    • resourcePath: string

      relative path to the REST API resource requested

    • Default value queryParams: object = {}

      parameters that will be added to the query string

      • [param: string]: string

    Returns Promise<T>

    A promise that in case of success will be fulfilled with the retrieved object. In case of any failure, it will be rejected with a Failure.

httpGetAll

  • httpGetAll<T>(baseUrl: string, resourcePath: string, queryParams: object, restBatchSize: number): Promise<T[]>
  • Returns a promise that will be fulfilled with the result of an HTTP GET request to a YouTrack REST array resource.

    This method sets the HTTP Authorization header if it is known due to a previous call to handlePotentialOauthRedirect(). If no authorization is available, this method rejects the promise immediately.

    Type parameters

    • T

      the element type of the array response by YouTrack (after parsing the JSON)

    Parameters

    • baseUrl: string

      The YouTrack base URL. See also httpGet().

    • resourcePath: string

      relative path to the REST API resource requested

    • queryParams: object

      parameters that will be added to the query string

      • [param: string]: string
    • restBatchSize: number

      Number of elements per HTTP request. Larger values are faster, but increase the risk of transmission problems (or outright rejection by future YouTrack versions that may have rate limitations).

    Returns Promise<T[]>

    A promise that in case of success will be fulfilled with the retrieved array. In case of any failure, it will be rejected with a Failure.

httpGetAllWithOptions

  • httpGetAllWithOptions<T, U>(baseUrl: string, resourcePath: string, queryParams: object, restBatchSize: number, processBatch: function, initial: U): Promise<U>
  • Returns a promise that will be fulfilled with a transformation of the result of an HTTP GET request to a YouTrack REST array resource.

    This method sets the HTTP Authorization header if it is known due to a previous call to handlePotentialOauthRedirect(). If no authorization is available, this method rejects the promise immediately.

    Type parameters

    • T

      the element type of the array response by YouTrack (after parsing the JSON)

    • U

      the return type of processBatch() and therefore also this function

    Parameters

    • baseUrl: string

      The YouTrack base URL. See also httpGet().

    • resourcePath: string

      relative path to the REST API resource requested

    • queryParams: object

      parameters that will be added to the query string

      • [param: string]: string
    • restBatchSize: number

      Number of elements per HTTP request. See also httpGetAll().

    • processBatch: function

      callback called for the result of each individual HTTP request

        • (batch: T[], previous: U): U
        • Parameters

          • batch: T[]

            the retrieved array

          • previous: U

            the state returned by the previous invocation of processBatch(), or the value of initial if this is the first invocation

          Returns U

    • initial: U

      the value passed to the first invocation of processBatch() as argument initial

    Returns Promise<U>

    A promise that in case of success will be fulfilled with the last result of processBatch(). In case of any failure, it will be rejected with a Failure.

isFailure

  • isFailure(value: any): boolean
  • Returns whether the given value is a Failure.

    Parameters

    • value: any

    Returns boolean

makeForest

  • makeForest<T>(issues: T[]): Iterable<IssueNode<T>>
  • Creates an issue tree (or forest) representing the given issues, and returns an iterable over all root nodes.

    Type parameters

    Parameters

    • issues: T[]

      Array of issues. The array is expected to be “closed” in the sense that a parent or dependency referenced by any of the issues is guaranteed to be contained in issues, too.

    Returns Iterable<IssueNode<T>>

    An iterable over all root nodes. The iterable will return the root nodes in the order they appeared in the array. Likewise, the children of each node (at any level) will be stored in input order.

retrieveProjectPlan

  • Retrieves, reconstructs, and returns a project plan consisting of the issues and their activities in a YouTrack saved search.

    This method requires that handlePotentialOauthRedirect() was called previously and obtained an OAuth token. The authorization should be valid for the expected duration of the data retrieval. YouTrack does not issue refresh tokens, so communication with YouTrack will fail otherwise.

    Parameters

    • baseUrl: string

      The YouTrack base URL. See also httpGet().

    • youTrackConfig: YouTrackConfig

      Configuration of YouTrack.

    • Optional options: RetrieveProjectPlanOptions

      Options for retrieving YouTrack issue data and building a project plan.

    Returns Promise<ProjectPlan>

    A promise that in case of success will be fulfilled with a project plan. In case of any failure, it will be rejected with a Failure.

scheduleUnresolved

  • Computes and returns a schedule for the given issues.

    The problem of scheduling issues is transformed (“reduced”) to the machine-scheduling problem, which is then solved using the list-scheduling algorithm from project fschopp/project-planning-js.

    Issues are scheduled in input order, subject to issue dependencies. Note that if an issue A depends on another issue B, then both A and its sub-issues (transitively) depend on both B and all of B’s sub-issues. Beyond that, parent-child relationships do not influence the scheduling order. That is, if both an issue and a sub-issues have non-zero remaining effort, then both issues’ own (excluding sub-issues) processing will occur in input order.

    Under the hood, this function introduces “dummy” jobs with size zero and zero delivery time. These dummy jobs (thanks to the transitive nature of dependencies) allow to “factor out” start-to-start and finish-to-finish dependencies (from issues to sub-issues and vice versa, respectively). Thus, the transformed machine-scheduling problem instance can be represented succinctly.

    Parameters

    • issues: SchedulableIssue[]

      Array of issues that need to be scheduled. The array is expected to be “closed” in the sense that a parent or dependency referenced by any of the issues is guaranteed to be contained in issues, too. That is, despite the name of this function, it is not expected that all issue are unresolved.

    • options: SchedulingOptions

      scheduling options

    Returns Promise<Schedule>

    promise that will be resolved with the schedule or rejected with a Failure containing a human-readable failure description if the problem instance is invalid (for example, has a cyclic dependency graph)

traverseIssueForest

  • traverseIssueForest<T>(rootNodes: Iterable<IssueNode<T>>, enterNode: function, leaveNode?: function): void
  • Traverses each of the given issue trees and invokes the given visitor functions.

    Type parameters

    Parameters

    • rootNodes: Iterable<IssueNode<T>>

      The root nodes of the trees making up the forest.

    • enterNode: function

      Visitor function that will be called on entering a node (that is, before any of its children have been visited).

        • Parameters

          • node: IssueNode<T>

            The node that is currently being visited.

          Returns void

    • Default value leaveNode: function = () => { /* no-op */ }

      Visitor function that will be called on leaving a node (that is, after all of its children have been visited).

        • Parameters

          • node: IssueNode<T>

            The node that is currently being visited.

          Returns void

    Returns void

Generated using TypeDoc