path.html

---
layout: default
---

  <div class="content">
    <h1>Path</h1>

     <div class="desc">
      <p>
       Paths are returned by <a href="collection#parsePath"><i>collection</i>.parsePath(<i>path</i>)</a>.  They are used to make writing
       generic metadata-based code easier.
     </p>
     <p>
       Path is also able to deal with <a href="/#denormalization">denormalized paths</a> as well.
     </p>
     <p>See <a href="/#paths">paths</a> for more information.</p>
    </div>

    <h3>static</h3>

     <article id="decode">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">decode(path: string): string</span>
       <p>This decodes a MongoDB-safe path string into a regular path string.</p>
     </article>

     <article id="encode">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">encode(path: string): string</span>
       <p>This encodes a regular path into a MongoDB-safe path string.</p>
       <p>MongoDB does not support periods appearing inside key names inside objects stored in MongoDB.  However, sometimes we need to store
         Tyranid metadata inside the database that uses Tyranid paths.  This method encodes those values into something that MongoDB will store.</p>
     </article>

     <article>
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">populateNameFor(name: string, denormal: boolean): string</span>
       <p>This returns the name for the populated field the given path.</p>
       <table>
         <tr><th><u>name</u><th><u>populateNameFor(denormal: false)/u><th><u>populateNameFor(denormal: true)</u>
         <tr><td><u>'customer'</u><td><u>'customer$'</u><td><u>'customer_'</u>
         <tr><td><u>'customerId'</u><td><u>'customer'</u><td><u>'customer_'</u>
       </table>
     </article>

     <article>
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">resolve(collection: <a href="collection">Collection</a>,<br>
          <div style="margin-left:98px">parentPath?: <a href="path">Path</a> | string,</div>
          <div style="margin-left:98px">path?: <a href="path">Path</a> | string): <a href="path">Path</a> | undefined</div></span>
       <p>This resolves a new <a href="path"><u>Path</u></a> instance from a parent path and a child path.</p>
       <p>If both the parent path and child path are missing, this will return <u>undefined</u>.</p>
     </article>

    <h3>instance</h3>

     <article id="$metaType">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">$metaType: 'path'</span>
       <p>This returns 'path'.</p>
     </article>

     <article id="base">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">base: <a href="collection">Collection</a> | <a href="path">Path</a></span>
       <p>This returns the object that this name path is relative to (usually a collection, but it could be relative to another name path).</p>
     </article>

     <article id="detail">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">detail: <a href="field">Field</a></span>
       <p>This is a more detailed version of <a href="path#tail"><u>tail</u></a>.</p>
       <p>Often you are only interested in the end of the path which has the <a href="type">Type</a> of the path you are working with.</p>
       <p>This is a shortcut for <u><i>skipArrays</i>(this.pathFields[this.pathFields.length-1])</u>.</p>
       <p>If the path <u>parent.children</u> refers to a an array of string, the <u>tail</u> points at the array but <u>detail</u> points
         at the contents of the array -- i.e. the string field.</p>
     </article>

     <article id="fields">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">fields: <a href="field">Field</a>[]</span>
       <p>
         This array contains the <a href="field">Field</a> for each step along the path.  This is a parallel array to <a href="path#path">path</a>.
       </p>
     </article>

     <article id="get">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">get(obj: object): any</span>
       <p>This walks the <u>obj</u> according to this path and returns the values at this path.  (There can be multiple values if the path crosses
       any arrays.  If so, this method will return duplicate values if values occur more than once.  See <a href="path#uniq"><u><i>Path</i>.uniq()</u></a>.)</p>
     </article>

     <article id="groupCount">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">groupCount: number</span>
       <p>This returns the number of path groups inside this path.  Groups are created by using a '|' instead of a '.' as a separatror.</p>
     </article>

     <article id="groupLabel">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">groupLabel(groupNumber: number): string</span>
       <p>This returns the label for the given group.  Groups are created by using a '|' instead of a '.' as a separatror.</p>
     </article>

     <article id="groupRange">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">groupRange(groupNumber: number): [number, number]</span>
       <p>This returns the range of fields for the given group.  Groups are created by using a '|' instead of a '.' as a separatror.</p>
     </article>

     <article id="identifier">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig"><a href="/#paths">identifier</a>: string</span>
       <p>This returns a simple identifier for this field that does not have periods (.) in it.</p>
       <p>This can be useful for some libraries which don't deal with with embedded periods like <u>getFieldDecorator</u>.</p>
       <p>For example:</p>
       <table>
         <tr><th>Path</th><th>Identifier</th></tr>
         <tr><td>siblings._.name</td><td>siblings___name</td></tr>
         <tr><td>name.first</td><td>name_first</td></tr>
         <tr><td>age</td><td>age</td></tr>
       </table>
     </article>

     <article id="isHistorical">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">isHistorical(): boolean</span>
       <p>This returns true if this path represents a <a href="/#historical">historical</a> property.</p>
     </article>

     <article id="label">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">label</a>: string</span>
       <p>This contains the full <a href="/#pathLabels">path label</a> for this name path.  This includes both
        the group and path portions.</p>
       <p>For example, given a path of <u>orders.location|city.name</u>:
       <table>
         <tr><th>Method</th><th>Label</th></tr>
         <tr><td><a href="#groupLabel">groupLabel(0)</a></td><td>Order Locations</td></tr>
         <tr><td><a href="#pathLabel">pathLabel</a></td><td>City</td></tr>
         <tr><td><a href="#label">label</a></td><td>Order Location City</td></tr>
       </table>
     </article>

     <article>
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">name: string</span>
       <p>This contains the full, unparsed path that was passed into the constructor.</p>
     </article>

     <article id="parsePath">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">parsePath(path: string): Path</span>
       <p>This returns a new <u>Path</u> relative to the current name path.  Any objects passed into methods on this new <u>Path</u> like <u>get</u>,
        <u>set</u>, and so on must also be relative in the same way.</p>
     </article>

     <article id="path">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">path: string[]</span>
       <p>This contains the path split up into individual strings for steps on the path.</p>
       <table>
         <tr><th><u><i>name</i></u><th><u>path(<i>name</i>)</u>
         <tr><td><u>'name'</u><td><u>[ 'name' ]</u>
         <tr><td><u>'name.first'</u><td><u>[ 'name', 'first' ]</u>
         <tr><td><u>'organization_.owner_.name.first'</u><td><u>[ 'organization_', 'owner_', 'name', 'first' ]</u>
       </table>
     </article>

     <article id="pathLabel">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig"><a href="/#paths">pathLabel</a>: string</span>
       <p>This contains the full <a href="/#pathLabels">path label</a> for this name path except for the
        group portion of this path (if any).
     </article>

     <article id="pathName">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">pathName(idx: integer): string</span>
       <p>This returns a verbose description of the path at position <u>idx</u> along the path.  This is useful for error messages in parsing.</p>
     </article>

     <article id="projectify">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">projectify(projection: <i>Mongo projection</i>): void</span>
       <p>This adds the current path to the given projection.</p>
       <p>If this path refers to a computed field, then all of the fields needed to perform the computation will be added to the projection
         as well.</p>
     </article>

     <article id="set">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">set(obj: object, value: any, opts: object): void</span>
       <p>This walks the <u>obj</u> according to this path and sets the given <u>value</u> at that point in the path.</p>
       <p><u>opts</u> is as follows:</p>
       <table class="def">
         <thead>
           <tr><th>Option<th>Type<th>Notes
         <tbody>
           <tr><td>{</td>
           <tr><td>  create:<td>boolean<td>If true, <u>set()</u> will create any missing ancestor objects or arrays as needed.</a>.
           <tr><td>  ignore:<td>boolean<td>If true, <u>set()</u> will silently fail if ancestor objects or arrays are missing.</a>.
           <tr><td>}</td>
       </table>
     </article>

     <article id="spath">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig"><a href="/#paths">spath</a>: string</span>
       <p>This contains the <a href="/#paths">simplified path</a> of this field.</p>
       <p>Simplified paths remove the array contents reference and are useful when working with MongoDB projections.
        For example:</p>
       <table>
         <tr><th>Path</th><th>Simplified Path</th></tr>
         <tr><td>siblings._.name</td><td>siblings.name</td></tr>
         <tr><td>siblings.0.name</td><td>siblings.name</td></tr>
         <tr><td>name.first</td><td>name.first</td></tr>
         <tr><td>age</td><td>age</td></tr>
       </table>
       <p>See <a href="/#paths">Paths</a> for more information.</p>
     </article>

     <article id="spathArr">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig"><a href="/#paths">spathArr</a>: string</span>
       <p>This contains the <a href="/#paths">simplified path</a> of this field that includes array indices.</p>
       <p>Simplified paths remove the array contents reference and are useful when working with MongoDB projections.
        For example:</p>
       <table>
         <tr><th>Path</th><th>Simplified Path</th></tr>
         <tr><td>siblings._.name</td><td>siblings.name</td></tr>
         <tr><td>siblings.0.name</td><td>siblings.0.name</td></tr>
         <tr><td>name.first</td><td>name.first</td></tr>
         <tr><td>age</td><td>age</td></tr>
       </table>
       <p>See <a href="/#paths">Paths</a> for more information.</p>
     </article>

     <article id="tail">
       <b class="property"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">tail: <a href="field">Field</a></span>
       <p>This is a shortcut for <u>this.pathFields[this.pathFields.length-1]</u>.  Often you are only interested in the end of the path which has
         the <a href="type">Type</a> of the path you are working with.</p>
       <p>This property is related to <a href="path#detail"><u>detail</u></a>.  If the path <u>parent.children</u> refers to a an array of string,
         the <u>tail</u> points at the array but <u>detail</u> points at the contents of the array -- i.e. the string field.</p>
     </article>

     <article id="uniq">
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">uniq(obj: object): any[]</span>
       <p>This walks the <u>obj</u> according to this path and returns the uniq values at this path it finds.  (There can be multiple
       values if the path crosses any arrays.)</p>
     </article>

     <article>
       <b class="method"></b>
       <b class="server"></b>
       <b class="client"></b>
       <span class="sig">walk(path?: <a href="path">Path</a> | string): <a href="path">Path</a></span>
       <p>This resolves a new <a href="path"><u>Path</u></a> instance that is relative to the current
        <a href="path"><u>Path</u></a>.</p>
     </article>

  </div>