Document permuteDomain

api/.gitignore

@@ -3,6 +3,7 @@ docs/*.md
 
 # subsequent PRs will un-ignore areas that are under review until
 # all docs are complete and we can drop this ignore file entirely
+!docs/tough-cookie.permutedomain.md
 !docs/tough-cookie.pathmatch.md
 !docs/tough-cookie.canonicaldomain.md
 !docs/tough-cookie.getpublicsuffix.md

api/docs/tough-cookie.permutedomain.md

@@ -0,0 +1,77 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [tough-cookie](./tough-cookie.md) &gt; [permuteDomain](./tough-cookie.permutedomain.md)
+
+## permuteDomain() function
+
+Generates the permutation of all possible values that [domainMatch()](./tough-cookie.domainmatch.md) the given `domain` parameter. The array is in shortest-to-longest order. Useful when building custom [Store](./tough-cookie.store.md) implementations.
+
+**Signature:**
+
+```typescript
+export declare function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | undefined;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+domain
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+the domain to generate permutations for
+
+
+</td></tr>
+<tr><td>
+
+allowSpecialUseDomain
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ flag to control if [Special Use Domains](https://www.rfc-editor.org/rfc/rfc6761.html) such as `localhost` should be allowed
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+string\[\] \| undefined
+
+## Example
+
+
+```
+permuteDomain('foo.bar.example.com')
+// ['example.com', 'bar.example.com', 'foo.bar.example.com']
+```
+

api/tough-cookie.api.md

@@ -278,7 +278,7 @@ export function parseDate(str: Nullable<string>): Date | undefined;
 // @public
 export function pathMatch(reqPath: string, cookiePath: string): boolean;
 
-// @public (undocumented)
+// @public
 export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | undefined;
 
 // @public

lib/permuteDomain.ts

@@ -1,39 +1,19 @@
-/*!
- * Copyright (c) 2015, Salesforce.com, Inc.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *
- * 1. Redistributions of source code must retain the above copyright notice,
- * this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright notice,
- * this list of conditions and the following disclaimer in the documentation
- * and/or other materials provided with the distribution.
+import { getPublicSuffix } from './getPublicSuffix'
+
+/**
+ * Generates the permutation of all possible values that {@link domainMatch} the given `domain` parameter. The
+ * array is in shortest-to-longest order. Useful when building custom {@link Store} implementations.
  *
- * 3. Neither the name of Salesforce.com nor the names of its contributors may
- * be used to endorse or promote products derived from this software without
- * specific prior written permission.
+ * @example
+ * ```
+ * permuteDomain('foo.bar.example.com')
+ * // ['example.com', 'bar.example.com', 'foo.bar.example.com']
+ * ```
  *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
+ * @public
+ * @param domain - the domain to generate permutations for
+ * @param allowSpecialUseDomain - flag to control if {@link https://www.rfc-editor.org/rfc/rfc6761.html | Special Use Domains} such as `localhost` should be allowed
  */
-'use strict'
-import { getPublicSuffix } from './getPublicSuffix'
-
-// Gives the permutation of all possible domainMatch()es of a given domain. The
-// array is in shortest-to-longest order.  Handy for indexing.
-
 export function permuteDomain(
   domain: string,
   allowSpecialUseDomain?: boolean,