@atproto/syntax 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @atproto/syntax
 
+## 0.5.4
+
+### Patch Changes
+
+- [#4806](https://github.com/bluesky-social/atproto/pull/4806) [`26d793a`](https://github.com/bluesky-social/atproto/commit/26d793af95a6fb3a50f9b2a97187d8ac4fecf676) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Avoid trailing slashes when stringifying an AtUri
+
+- [#4806](https://github.com/bluesky-social/atproto/pull/4806) [`26d793a`](https://github.com/bluesky-social/atproto/commit/26d793af95a6fb3a50f9b2a97187d8ac4fecf676) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Align implementation of `ensureValidAtUri` and `ensureValidAtUriRegex`: consistently apply length and fragment charset restrictions
+
+- [#4806](https://github.com/bluesky-social/atproto/pull/4806) [`26d793a`](https://github.com/bluesky-social/atproto/commit/26d793af95a6fb3a50f9b2a97187d8ac4fecf676) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Improve performances of `AtUriString` validation
+
+- [#4760](https://github.com/bluesky-social/atproto/pull/4760) [`55d06de`](https://github.com/bluesky-social/atproto/commit/55d06de80a1506908a04ed5c0834986cb5783797) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fixes a bug where `normalizeDatetime` would return different results for the same input depending on the timezone of the machine it was run on. This caused tests to fail when run in different environments. The fix consists of attempting more consistent parsing strategies first (appending "Z" or " UTC" to the input) before falling back to parsing "as is", which can yield different results depending on the local timezone. The function's documentation has also been updated to reflect this behavior.
+
+- [#4806](https://github.com/bluesky-social/atproto/pull/4806) [`26d793a`](https://github.com/bluesky-social/atproto/commit/26d793af95a6fb3a50f9b2a97187d8ac4fecf676) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add missing fragment to `AtUriString` template literal type
+
+## 0.5.3
+
+### Patch Changes
+
+- [#4815](https://github.com/bluesky-social/atproto/pull/4815) [`3711454`](https://github.com/bluesky-social/atproto/commit/371145432178b6c8c411f1289c266314cc7ec592) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Rewrite of tests
+
 ## 0.5.2
 
 ### Patch Changes

package/dist/aturi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aturi.d.ts","sourceRoot":"","sources":["../src/aturi.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAGnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,SAAS,EAAmB,MAAM,UAAU,CAAA;AACrD,OAAO,EAAE,UAAU,EAAmB,MAAM,WAAW,CAAA;AACvD,OAAO,EAAE,eAAe,EAAwB,MAAM,gBAAgB,CAAA;AAEtE,cAAc,uBAAuB,CAAA;AAGrC,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,UAAU,EACV,eAAe,GAChB,CAAA;AAED,eAAO,MAAM,aAAa,QAEyE,CAAA;AAInG,qBAAa,KAAK;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,kBAAkB,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,eAAe,CAAA;gBAEjB,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK;IAgB9C,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;IAOnE,IAAI,QAAQ,WAEX;IAED,IAAI,MAAM,gEAET;IAED,IAAI,GAAG,IAAI,SAAS,CAInB;IAED,IAAI,QAAQ,IAAI,kBAAkB,CAEjC;IAED,IAAI,QAAQ,CAAC,CAAC,EAAE,MAAM,EAGrB;IAED,IAAI,MAAM,IAII,MAAM,CAFnB;IAED,IAAI,MAAM,CAAC,CAAC,EAAE,MAAM,EAEnB;IAED,IAAI,UAAU,IAUI,MAAM,CARvB;IAED,IAAI,cAAc,IAAI,UAAU,CAI/B;IAED,IAAI,UAAU,CAAC,CAAC,EAAE,MAAM,EAGvB;IAED,qBAAqB,CAAC,CAAC,EAAE,MAAM;IAM/B,IAAI,IAAI,IAUI,MAAM,CARjB;IAED,IAAI,QAAQ,IAAI,eAAe,CAI9B;IAED,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,EAGjB;IAED,eAAe,CAAC,CAAC,EAAE,MAAM;IAOzB,IAAI,IAAI,gBAEP;IAED,QAAQ,IAAI,WAAW;CAexB"}
+{"version":3,"file":"aturi.d.ts","sourceRoot":"","sources":["../src/aturi.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAGnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,SAAS,EAAmB,MAAM,UAAU,CAAA;AACrD,OAAO,EAAE,UAAU,EAAmB,MAAM,WAAW,CAAA;AACvD,OAAO,EAAE,eAAe,EAAwB,MAAM,gBAAgB,CAAA;AAEtE,cAAc,uBAAuB,CAAA;AAGrC,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,UAAU,EACV,eAAe,GAChB,CAAA;AAED,eAAO,MAAM,aAAa,QAEyE,CAAA;AAInG,qBAAa,KAAK;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,kBAAkB,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,eAAe,CAAA;gBAEjB,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK;IAgB9C,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;IAOnE,IAAI,QAAQ,WAEX;IAED,IAAI,MAAM,gEAET;IAED,IAAI,GAAG,IAAI,SAAS,CAInB;IAED,IAAI,QAAQ,IAAI,kBAAkB,CAEjC;IAED,IAAI,QAAQ,CAAC,CAAC,EAAE,MAAM,EAGrB;IAED,IAAI,MAAM,IAII,MAAM,CAFnB;IAED,IAAI,MAAM,CAAC,CAAC,EAAE,MAAM,EAEnB;IAED,IAAI,UAAU,IAUI,MAAM,CARvB;IAED,IAAI,cAAc,IAAI,UAAU,CAI/B;IAED,IAAI,UAAU,CAAC,CAAC,EAAE,MAAM,EAGvB;IAED,qBAAqB,CAAC,CAAC,EAAE,MAAM;IAM/B,IAAI,IAAI,IAUI,MAAM,CARjB;IAED,IAAI,QAAQ,IAAI,eAAe,CAI9B;IAED,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,EAGjB;IAED,eAAe,CAAC,CAAC,EAAE,MAAM;IAOzB,IAAI,IAAI,gBAEP;IAED,QAAQ,IAAI,WAAW;CAqBxB"}

package/dist/aturi.js

@@ -101,19 +101,26 @@ class AtUri {
         return this.toString();
     }
     toString() {
-        let path = this.pathname || '/';
-        if (!path.startsWith('/')) {
-            path = `/${path}`;
+        let pathname = this.pathname;
+        if (pathname && !pathname.startsWith('/')) {
+            pathname = `/${pathname}`;
+        }
+        while (pathname.endsWith('/')) {
+            pathname = pathname.slice(0, -1);
         }
         let qs = '';
         if (this.searchParams.size) {
             qs = `?${this.searchParams.toString()}`;
         }
-        let hash = this.hash;
-        if (hash && !hash.startsWith('#')) {
-            hash = `#${hash}`;
+        // @NOTE We keep the hash as-is, even if it doesn't start with a '/'.
+        let fragment = this.hash;
+        if (fragment === '#') {
+            fragment = '';
+        }
+        else if (fragment && !fragment.startsWith('#')) {
+            fragment = `#${fragment}`;
         }
-        return `at://${this.host}${path}${qs}${hash}`;
+        return `at://${this.host}${pathname}${qs}${fragment}`;
     }
 }
 exports.AtUri = AtUri;

package/dist/aturi.js.map

@@ -1 +1 @@
-{"version":3,"file":"aturi.js","sourceRoot":"","sources":["../src/aturi.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  AtIdentifierString,\n  ensureValidAtIdentifier,\n  isDidIdentifier,\n} from './at-identifier.js'\nimport { AtUriString } from './aturi_validation.js'\nimport { DidString, InvalidDidError } from './did.js'\nimport { NsidString, ensureValidNsid } from './nsid.js'\nimport { RecordKeyString, ensureValidRecordKey } from './recordkey.js'\n\nexport * from './aturi_validation.js'\n\n// Re-export types used in public interface\nexport type {\n  AtIdentifierString,\n  AtUriString,\n  DidString,\n  NsidString,\n  RecordKeyString,\n}\n\nexport const ATP_URI_REGEX =\n  // proto-    --did--------------   --name----------------   --path----   --query--   --hash--\n  /^(at:\\/\\/)?((?:did:[a-z0-9:%-]+)|(?:[a-z0-9][a-z0-9.:-]*))(\\/[^?#\\s]*)?(\\?[^#\\s]+)?(#[^\\s]+)?$/i\n//                       --path-----   --query--  --hash--\nconst RELATIVE_REGEX = /^(\\/[^?#\\s]*)?(\\?[^#\\s]+)?(#[^\\s]+)?$/i\n\nexport class AtUri {\n  hash: string\n  host: AtIdentifierString\n  pathname: string\n  searchParams: URLSearchParams\n\n  constructor(uri: string, base?: string | AtUri) {\n    const parsed =\n      base !== undefined\n        ? typeof base === 'string'\n          ? Object.assign(parse(base), parseRelative(uri))\n          : Object.assign({ host: base.host }, parseRelative(uri))\n        : parse(uri)\n\n    ensureValidAtIdentifier(parsed.host)\n\n    this.hash = parsed.hash ?? ''\n    this.host = parsed.host\n    this.pathname = parsed.pathname ?? ''\n    this.searchParams = parsed.searchParams\n  }\n\n  static make(handleOrDid: string, collection?: string, rkey?: string) {\n    let str = handleOrDid\n    if (collection) str += '/' + collection\n    if (rkey) str += '/' + rkey\n    return new AtUri(str)\n  }\n\n  get protocol() {\n    return 'at:'\n  }\n\n  get origin() {\n    return `at://${this.host}` as const\n  }\n\n  get did(): DidString {\n    const { host } = this\n    if (isDidIdentifier(host)) return host\n    throw new InvalidDidError(`AtUri \"${this}\" does not have a DID hostname`)\n  }\n\n  get hostname(): AtIdentifierString {\n    return this.host\n  }\n\n  set hostname(v: string) {\n    ensureValidAtIdentifier(v)\n    this.host = v\n  }\n\n  get search() {\n    return this.searchParams.toString()\n  }\n\n  set search(v: string) {\n    this.searchParams = new URLSearchParams(v)\n  }\n\n  get collection() {\n    return this.pathname.split('/').filter(Boolean)[0] || ''\n  }\n\n  get collectionSafe(): NsidString {\n    const { collection } = this\n    ensureValidNsid(collection)\n    return collection\n  }\n\n  set collection(v: string) {\n    ensureValidNsid(v)\n    this.unsafelySetCollection(v)\n  }\n\n  unsafelySetCollection(v: string) {\n    const parts = this.pathname.split('/').filter(Boolean)\n    parts[0] = v\n    this.pathname = parts.join('/')\n  }\n\n  get rkey() {\n    return this.pathname.split('/').filter(Boolean)[1] || ''\n  }\n\n  get rkeySafe(): RecordKeyString {\n    const { rkey } = this\n    ensureValidRecordKey(rkey)\n    return rkey\n  }\n\n  set rkey(v: string) {\n    ensureValidRecordKey(v)\n    this.unsafelySetRkey(v)\n  }\n\n  unsafelySetRkey(v: string) {\n    const parts = this.pathname.split('/').filter(Boolean)\n    parts[0] ||= 'undefined'\n    parts[1] = v\n    this.pathname = parts.join('/')\n  }\n\n  get href() {\n    return this.toString()\n  }\n\n  toString(): AtUriString {\n    let path = this.pathname || '/'\n    if (!path.startsWith('/')) {\n      path = `/${path}`\n    }\n    let qs = ''\n    if (this.searchParams.size) {\n      qs = `?${this.searchParams.toString()}`\n    }\n    let hash = this.hash\n    if (hash && !hash.startsWith('#')) {\n      hash = `#${hash}`\n    }\n    return `at://${this.host}${path}${qs}${hash}` as AtUriString\n  }\n}\n\nfunction parse(str: string) {\n  const match = str.match(ATP_URI_REGEX) as null | {\n    0: string\n    1: string | undefined // proto\n    2: string // host\n    3: string | undefined // path\n    4: string | undefined // query\n    5: string | undefined // hash\n  }\n\n  if (!match) {\n    throw new Error(`Invalid AT uri: ${str}`)\n  }\n\n  return {\n    host: match[2],\n    hash: match[5],\n    pathname: match[3],\n    searchParams: new URLSearchParams(match[4]),\n  }\n}\n\nfunction parseRelative(str: string) {\n  const match = str.match(RELATIVE_REGEX) as null | {\n    0: string\n    1: string | undefined // path\n    2: string | undefined // query\n    3: string | undefined // hash\n  }\n\n  if (!match) {\n    throw new Error(`Invalid path: ${str}`)\n  }\n\n  return {\n    hash: match[3],\n    pathname: match[1],\n    searchParams: new URLSearchParams(match[2]),\n  }\n}\n"]}
+{"version":3,"file":"aturi.js","sourceRoot":"","sources":["../src/aturi.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  AtIdentifierString,\n  ensureValidAtIdentifier,\n  isDidIdentifier,\n} from './at-identifier.js'\nimport { AtUriString } from './aturi_validation.js'\nimport { DidString, InvalidDidError } from './did.js'\nimport { NsidString, ensureValidNsid } from './nsid.js'\nimport { RecordKeyString, ensureValidRecordKey } from './recordkey.js'\n\nexport * from './aturi_validation.js'\n\n// Re-export types used in public interface\nexport type {\n  AtIdentifierString,\n  AtUriString,\n  DidString,\n  NsidString,\n  RecordKeyString,\n}\n\nexport const ATP_URI_REGEX =\n  // proto-    --did--------------   --name----------------   --path----   --query--   --hash--\n  /^(at:\\/\\/)?((?:did:[a-z0-9:%-]+)|(?:[a-z0-9][a-z0-9.:-]*))(\\/[^?#\\s]*)?(\\?[^#\\s]+)?(#[^\\s]+)?$/i\n//                       --path-----   --query--  --hash--\nconst RELATIVE_REGEX = /^(\\/[^?#\\s]*)?(\\?[^#\\s]+)?(#[^\\s]+)?$/i\n\nexport class AtUri {\n  hash: string\n  host: AtIdentifierString\n  pathname: string\n  searchParams: URLSearchParams\n\n  constructor(uri: string, base?: string | AtUri) {\n    const parsed =\n      base !== undefined\n        ? typeof base === 'string'\n          ? Object.assign(parse(base), parseRelative(uri))\n          : Object.assign({ host: base.host }, parseRelative(uri))\n        : parse(uri)\n\n    ensureValidAtIdentifier(parsed.host)\n\n    this.hash = parsed.hash ?? ''\n    this.host = parsed.host\n    this.pathname = parsed.pathname ?? ''\n    this.searchParams = parsed.searchParams\n  }\n\n  static make(handleOrDid: string, collection?: string, rkey?: string) {\n    let str = handleOrDid\n    if (collection) str += '/' + collection\n    if (rkey) str += '/' + rkey\n    return new AtUri(str)\n  }\n\n  get protocol() {\n    return 'at:'\n  }\n\n  get origin() {\n    return `at://${this.host}` as const\n  }\n\n  get did(): DidString {\n    const { host } = this\n    if (isDidIdentifier(host)) return host\n    throw new InvalidDidError(`AtUri \"${this}\" does not have a DID hostname`)\n  }\n\n  get hostname(): AtIdentifierString {\n    return this.host\n  }\n\n  set hostname(v: string) {\n    ensureValidAtIdentifier(v)\n    this.host = v\n  }\n\n  get search() {\n    return this.searchParams.toString()\n  }\n\n  set search(v: string) {\n    this.searchParams = new URLSearchParams(v)\n  }\n\n  get collection() {\n    return this.pathname.split('/').filter(Boolean)[0] || ''\n  }\n\n  get collectionSafe(): NsidString {\n    const { collection } = this\n    ensureValidNsid(collection)\n    return collection\n  }\n\n  set collection(v: string) {\n    ensureValidNsid(v)\n    this.unsafelySetCollection(v)\n  }\n\n  unsafelySetCollection(v: string) {\n    const parts = this.pathname.split('/').filter(Boolean)\n    parts[0] = v\n    this.pathname = parts.join('/')\n  }\n\n  get rkey() {\n    return this.pathname.split('/').filter(Boolean)[1] || ''\n  }\n\n  get rkeySafe(): RecordKeyString {\n    const { rkey } = this\n    ensureValidRecordKey(rkey)\n    return rkey\n  }\n\n  set rkey(v: string) {\n    ensureValidRecordKey(v)\n    this.unsafelySetRkey(v)\n  }\n\n  unsafelySetRkey(v: string) {\n    const parts = this.pathname.split('/').filter(Boolean)\n    parts[0] ||= 'undefined'\n    parts[1] = v\n    this.pathname = parts.join('/')\n  }\n\n  get href() {\n    return this.toString()\n  }\n\n  toString(): AtUriString {\n    let pathname = this.pathname\n    if (pathname && !pathname.startsWith('/')) {\n      pathname = `/${pathname}`\n    }\n    while (pathname.endsWith('/')) {\n      pathname = pathname.slice(0, -1)\n    }\n    let qs = ''\n    if (this.searchParams.size) {\n      qs = `?${this.searchParams.toString()}`\n    }\n    // @NOTE We keep the hash as-is, even if it doesn't start with a '/'.\n    let fragment = this.hash\n    if (fragment === '#') {\n      fragment = ''\n    } else if (fragment && !fragment.startsWith('#')) {\n      fragment = `#${fragment}`\n    }\n    return `at://${this.host}${pathname}${qs}${fragment}` as AtUriString\n  }\n}\n\nfunction parse(str: string) {\n  const match = str.match(ATP_URI_REGEX) as null | {\n    0: string\n    1: string | undefined // proto\n    2: string // host\n    3: string | undefined // path\n    4: string | undefined // query\n    5: string | undefined // hash\n  }\n\n  if (!match) {\n    throw new Error(`Invalid AT uri: ${str}`)\n  }\n\n  return {\n    host: match[2],\n    hash: match[5],\n    pathname: match[3],\n    searchParams: new URLSearchParams(match[4]),\n  }\n}\n\nfunction parseRelative(str: string) {\n  const match = str.match(RELATIVE_REGEX) as null | {\n    0: string\n    1: string | undefined // path\n    2: string | undefined // query\n    3: string | undefined // hash\n  }\n\n  if (!match) {\n    throw new Error(`Invalid path: ${str}`)\n  }\n\n  return {\n    hash: match[3],\n    pathname: match[1],\n    searchParams: new URLSearchParams(match[2]),\n  }\n}\n"]}

package/dist/aturi_validation.d.ts

@@ -1,7 +1,140 @@
 import { AtIdentifierString } from './at-identifier.js';
+import { Result } from './lib/result.js';
 import { NsidString } from './nsid.js';
-export type AtUriString = `at://${AtIdentifierString}` | `at://${AtIdentifierString}/${NsidString}` | `at://${AtIdentifierString}/${NsidString}/${string}`;
-export declare function ensureValidAtUri<I extends string>(input: I): asserts input is I & AtUriString;
-export declare function ensureValidAtUriRegex<I extends string>(input: I): asserts input is I & AtUriString;
-export declare function isValidAtUri<I extends string>(input: I): input is I & AtUriString;
+export type AtUriStringBase = `at://${AtIdentifierString}` | `at://${AtIdentifierString}/${NsidString}` | `at://${AtIdentifierString}/${NsidString}/${string}`;
+export type AtUriStringFragment = `#/${string}`;
+/**
+ * A URI string as used to point at resources in the AT Protocol
+ *
+ * The full, general structure of an AT URI is:
+ *
+ * ```bnf
+ * AT-URI = "at://" AUTHORITY [ PATH ] [ "?" QUERY ] [ "#" FRAGMENT ]
+ * ```
+ *
+ * The authority part of the URI can be either a handle or a DID, indicating the
+ * identity associated with the repository. In current atproto Lexicon use, the
+ * query and fragment parts are not yet supported, and only a fixed pattern of
+ * paths are allowed:
+ *
+ * ```bnf
+ * AT-URI     = "at://" AUTHORITY [ "/" COLLECTION [ "/" RKEY ] ]
+ *
+ * AUTHORITY  = HANDLE | DID
+ * COLLECTION = NSID
+ * RKEY       = RECORD-KEY
+ * ```
+ *
+ * The authority section is required, and should be normalized.
+ *
+ * AT URI strings must respect the following syntax (as prescribed by the AT
+ * protocol specification):
+ *
+ * - The overall URI is restricted to a subset of ASCII characters
+ * - For reference below, the set of unreserved characters, as defined in [RFC-3986](https://www.rfc-editor.org/rfc/rfc3986), includes alphanumeric (`A-Za-z0-9`), period, hyphen, underscore, and tilde (`.-_~`)
+ * - Maximum overall length is 8 kilobytes (which may be shortened in the future)
+ * - Hex-encoding of characters is permitted (but in practice not necessary and should be avoided to keep the URI normalized and human-readable)
+ * - The URI scheme is `at`, and an authority part preceded with double slashes is always required. AT URIs always start with `at://`.
+ * - An authority section is required and must be non-empty. the authority can be either an atproto Handle, or a DID meeting the restrictions for use with atproto. The authority part can *not* be interpreted as a host:port pair, because of the use of colon characters (`:`) in DIDs. Colons and unreserved characters should not be escaped in DIDs, but other reserved characters (including `#`, `/`, `$`, `&`, `@`) must be escaped.
+ *     - Note that none of the current "blessed" DID methods for atproto allow these characters in DID identifiers
+ * - An optional path section may follow the authority. The path may contain multiple segments separated by a single slash (`/`). Generic URI path normalization rules may be used.
+ * - An optional query part is allowed, following generic URI syntax restrictions
+ * - An optional fragment part is allowed, using JSON Path syntax
+ *
+ * @example "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.actor.profile/self"
+ *
+ * @see {@link https://atproto.com/specs/at-uri-scheme AT protocol - AT URI Scheme}
+ */
+export type AtUriString = AtUriStringBase | `${AtUriStringBase}${AtUriStringFragment}`;
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString}
+ *
+ * @see {@link AtUriString}
+ */
+export declare function isAtUriString<I>(input: I, options?: Omit<ParseAtUriStringOptions, 'detailed'>): input is I & AtUriString;
+/**
+ * Returns the input if it is a valid {@link AtUriString} format string, or
+ * `undefined` if it is not.
+ *
+ * @see {@link AtUriString}
+ */
+export declare function ifAtUriString<I>(input: I, options?: Omit<ParseAtUriStringOptions, 'detailed'>): undefined | (I & AtUriString);
+/**
+ * Casts a string to an {@link AtUriString} if it is a valid AT URI format
+ * string, throwing an error if it is not.
+ *
+ * @throws InvalidAtUriError if the input string does not meet the atproto AT URI format requirements.
+ * @see {@link AtUriString}
+ */
+export declare function asAtUriString<I>(input: I, options?: ParseAtUriStringOptions): I & AtUriString;
+/**
+ * Assert the validity of an {@link AtUriString}, throwing an error if the
+ * {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ */
+export declare function assertAtUriString<I>(input: I, options?: ParseAtUriStringOptions): asserts input is I & AtUriString;
+/**
+ * Assert the **non-strict** validity of an {@link AtUriString}, throwing a
+ * detailed error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export declare function ensureValidAtUri<I>(input: I): asserts input is I & AtUriString;
+/**
+ * Assert the (non-strict!) validity of an {@link AtUriString}, throwing an
+ * error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export declare function ensureValidAtUriRegex<I>(input: I): asserts input is I & AtUriString;
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString} format
+ * string, without enforcing strict record key validation. This is useful for
+ * cases where you want to allow a wider range of valid ATURIs, such as when
+ * validating user input or when the record key is not relevant.
+ *
+ * @deprecated use {@link isAtUriString} with `{ strict: false }` option instead
+ */
+export declare function isValidAtUri<I>(input: I): input is I & AtUriString;
+export declare class InvalidAtUriError extends Error {
+}
+export type ParseAtUriStringOptions = {
+    /**
+     * If true, the parser will enforce that the record key (rkey) part of the URI
+     * is a valid record key (validated by {@link isValidRecordKey}). If false,
+     * any non-empty string of allowed chars will be accepted as a record key.
+     *
+     * @default true
+     */
+    strict?: boolean;
+    /**
+     * If true, the parser will return detailed error messages for why a string is
+     * not a valid AT URI. This option has no effect on the behavior of
+     * {@link isAtUriString}, which will always return false for invalid strings
+     * regardless of this option.
+     *
+     * @default false
+     */
+    detailed?: boolean;
+};
+export type AtUriParts = {
+    authority: AtIdentifierString;
+    query?: string;
+    hash?: string;
+} & ({
+    collection?: NsidString;
+    rkey?: undefined;
+} | {
+    collection: NsidString;
+    rkey?: string;
+});
+/**
+ * Parses a valid {@link AtUriString} into a {@link AtUriParts} object, or
+ * returns a failure with a detailed error message if the string is not a valid
+ * {@link AtUriString}.
+ */
+export declare function parseAtUriString(input: unknown, options?: ParseAtUriStringOptions): Result<AtUriParts>;
 //# sourceMappingURL=aturi_validation.d.ts.map

package/dist/aturi_validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aturi_validation.d.ts","sourceRoot":"","sources":["../src/aturi_validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA2B,MAAM,oBAAoB,CAAA;AAGhF,OAAO,EAAE,UAAU,EAAe,MAAM,WAAW,CAAA;AAEnD,MAAM,MAAM,WAAW,GACnB,QAAQ,kBAAkB,EAAE,GAC5B,QAAQ,kBAAkB,IAAI,UAAU,EAAE,GAC1C,QAAQ,kBAAkB,IAAI,UAAU,IAAI,MAAM,EAAE,CAAA;AAgBxD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,WAAW,CAiFlC;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,WAAW,CA4BlC;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,KAAK,EAAE,CAAC,GACP,KAAK,IAAI,CAAC,GAAG,WAAW,CAQ1B"}
+{"version":3,"file":"aturi_validation.d.ts","sourceRoot":"","sources":["../src/aturi_validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAwB,MAAM,oBAAoB,CAAA;AAC7E,OAAO,EAAE,MAAM,EAAoB,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAe,MAAM,WAAW,CAAA;AAGnD,MAAM,MAAM,eAAe,GACvB,QAAQ,kBAAkB,EAAE,GAC5B,QAAQ,kBAAkB,IAAI,UAAU,EAAE,GAC1C,QAAQ,kBAAkB,IAAI,UAAU,IAAI,MAAM,EAAE,CAAA;AAExD,MAAM,MAAM,mBAAmB,GAAG,KAAK,MAAM,EAAE,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,GAAG,eAAe,GAAG,mBAAmB,EAAE,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAClD,KAAK,IAAI,CAAC,GAAG,WAAW,CAE1B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAClD,SAAS,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAE/B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,uBAAuB,GAChC,CAAC,GAAG,WAAW,CAGjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,WAAW,CASlC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,WAAW,CAElC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,WAAW,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,WAAW,CAElE;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,kBAAkB,CAAA;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GAAG,CACA;IAAE,UAAU,CAAC,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GAC7C;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAC5C,CAAA;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAAC,UAAU,CAAC,CAsFpB"}

package/dist/aturi_validation.js

@@ -1,118 +1,200 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidAtUriError = void 0;
+exports.isAtUriString = isAtUriString;
+exports.ifAtUriString = ifAtUriString;
+exports.asAtUriString = asAtUriString;
+exports.assertAtUriString = assertAtUriString;
 exports.ensureValidAtUri = ensureValidAtUri;
 exports.ensureValidAtUriRegex = ensureValidAtUriRegex;
 exports.isValidAtUri = isValidAtUri;
+exports.parseAtUriString = parseAtUriString;
 const at_identifier_js_1 = require("./at-identifier.js");
-const did_js_1 = require("./did.js");
-const handle_js_1 = require("./handle.js");
+const result_js_1 = require("./lib/result.js");
 const nsid_js_1 = require("./nsid.js");
-// Human-readable constraints on ATURI:
-//   - following regular URLs, a 8KByte hard total length limit
-//   - follows ATURI docs on website
-//      - all ASCII characters, no whitespace. non-ASCII could be URL-encoded
-//      - starts "at://"
-//      - "authority" is a valid DID or a valid handle
-//      - optionally, follow "authority" with "/" and valid NSID as start of path
-//      - optionally, if NSID given, follow that with "/" and rkey
-//      - rkey path component can include URL-encoded ("percent encoded"), or:
-//          ALPHA / DIGIT / "-" / "." / "_" / "~" / ":" / "@" / "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
-//          [a-zA-Z0-9._~:@!$&'\(\)*+,;=-]
-//      - rkey must have at least one char
-//      - regardless of path component, a fragment can follow  as "#" and then a JSON pointer (RFC-6901)
+const recordkey_js_1 = require("./recordkey.js");
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString}
+ *
+ * @see {@link AtUriString}
+ */
+function isAtUriString(input, options) {
+    return parseAtUriString(input, options).success;
+}
+/**
+ * Returns the input if it is a valid {@link AtUriString} format string, or
+ * `undefined` if it is not.
+ *
+ * @see {@link AtUriString}
+ */
+function ifAtUriString(input, options) {
+    return isAtUriString(input, options) ? input : undefined;
+}
+/**
+ * Casts a string to an {@link AtUriString} if it is a valid AT URI format
+ * string, throwing an error if it is not.
+ *
+ * @throws InvalidAtUriError if the input string does not meet the atproto AT URI format requirements.
+ * @see {@link AtUriString}
+ */
+function asAtUriString(input, options) {
+    assertAtUriString(input, options);
+    return input;
+}
+/**
+ * Assert the validity of an {@link AtUriString}, throwing an error if the
+ * {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ */
+function assertAtUriString(input, options) {
+    // Optimistically use faster isAtUriString(), throwing a detailed error only
+    // in case of failure. This check, and the fact that the code after it always
+    // throws, also ensures that isAtUriString() and assertAtUriString()'s
+    // behavior are always consistent.
+    const result = parseAtUriString(input, options);
+    if (!result.success) {
+        throw new InvalidAtUriError(result.message);
+    }
+}
+/**
+ * Assert the **non-strict** validity of an {@link AtUriString}, throwing a
+ * detailed error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
 function ensureValidAtUri(input) {
-    const fragmentIndex = input.indexOf('#');
-    if (fragmentIndex !== -1) {
-        if (input.charCodeAt(fragmentIndex + 1) !== 47) {
-            throw new Error('ATURI fragment must be non-empty and start with slash');
+    assertAtUriString(input, { strict: false, detailed: true });
+}
+/**
+ * Assert the (non-strict!) validity of an {@link AtUriString}, throwing an
+ * error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+function ensureValidAtUriRegex(input) {
+    assertAtUriString(input, { strict: false, detailed: false });
+}
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString} format
+ * string, without enforcing strict record key validation. This is useful for
+ * cases where you want to allow a wider range of valid ATURIs, such as when
+ * validating user input or when the record key is not relevant.
+ *
+ * @deprecated use {@link isAtUriString} with `{ strict: false }` option instead
+ */
+function isValidAtUri(input) {
+    return isAtUriString(input, { strict: false });
+}
+class InvalidAtUriError extends Error {
+}
+exports.InvalidAtUriError = InvalidAtUriError;
+const INVALID_CHAR_REGEXP = /[^a-zA-Z0-9._~:@!$&'()*+,;=%/\\[\]#?-]/;
+const AT_URI_REGEXP = /^(?<uri>at:\/\/(?<authority>[^/?#\s]+)(?:\/(?<collection>[^/?#\s]+)(?:\/(?<rkey>[^/?#\s]+))?)?(?<trailingSlash>\/)?)(?:\?(?<query>[^#\s]*))?(?:#(?<hash>[^\s]*))?$/;
+/**
+ * Parses a valid {@link AtUriString} into a {@link AtUriParts} object, or
+ * returns a failure with a detailed error message if the string is not a valid
+ * {@link AtUriString}.
+ */
+function parseAtUriString(input, options) {
+    if (typeof input !== 'string') {
+        return (0, result_js_1.failure)('ATURI must be a string');
+    }
+    if (input.length > 8192) {
+        return (0, result_js_1.failure)('ATURI exceeds maximum length');
+    }
+    const invalidChar = input.match(INVALID_CHAR_REGEXP);
+    if (invalidChar) {
+        return (0, result_js_1.failure)('Disallowed characters in ATURI (ASCII)');
+    }
+    const match = input.match(AT_URI_REGEXP);
+    const groups = match?.groups;
+    if (!groups) {
+        // Regex validation failed, but we don't know exactly why. Provide more
+        // detailed error messages if the "detailed" option is set, falling back to
+        // a generic error.
+        if (options?.detailed) {
+            if (!input.startsWith('at://')) {
+                return (0, result_js_1.failure)('ATURI must start with "at://"');
+            }
+            if (input.includes(' ')) {
+                return (0, result_js_1.failure)('ATURI can not contain spaces');
+            }
+            if (input.includes('//', 5)) {
+                return (0, result_js_1.failure)('ATURI can not have empty path segments');
+            }
+            const pathStart = input.indexOf('/', 5); // after "at://"
+            if (pathStart !== -1) {
+                const fragmentIndex = input.indexOf('#');
+                const pathEnd = fragmentIndex !== -1 ? fragmentIndex : input.length;
+                const secondSlash = input.indexOf('/', pathStart + 1);
+                if (secondSlash !== -1 && secondSlash !== pathEnd - 1) {
+                    return (0, result_js_1.failure)('ATURI can not have more than two path segments');
+                }
+            }
         }
-        if (input.includes('#', fragmentIndex + 1)) {
-            throw new Error('ATURI can have at most one "#", separating fragment out');
+        return (0, result_js_1.failure)('ATURI does not match expected format');
+    }
+    // @NOTE Percent-encoding is allowed by the AT URI specification, but any
+    // percent-encoded characters appearing in the collection NSID or record key
+    // will effectively be rejected by the isValidNsid and isValidRecordKey
+    // validators. Since these values are defined to be plain ASCII identifiers,
+    // this legacy behavior is beneficial: it ensures that normalized
+    // (non-percent-encoded) values are always used, as prescribed by the spec.
+    if (!(0, at_identifier_js_1.isAtIdentifierString)(groups.authority)) {
+        return (0, result_js_1.failure)('ATURI has invalid authority');
+    }
+    if (groups.collection != null && !(0, nsid_js_1.isValidNsid)(groups.collection)) {
+        return (0, result_js_1.failure)('ATURI has invalid collection');
+    }
+    if (groups.hash != null) {
+        const result = parseJsonPointer(groups.hash, options);
+        if (result.success) {
+            groups.hash = result.value;
         }
-        // NOTE: enforcing *some* checks here for sanity. Eg, at least no whitespace
-        const fragment = input.slice(fragmentIndex + 1);
-        if (!/^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/.test(fragment)) {
-            throw new Error('Disallowed characters in ATURI fragment (ASCII)');
+        else {
+            return (0, result_js_1.failure)(`ATURI has invalid fragment (${result.message})`);
         }
     }
-    const uri = fragmentIndex === -1 ? input : input.slice(0, fragmentIndex);
-    if (uri.length > 8 * 1024) {
-        throw new Error('ATURI is far too long');
-    }
-    if (!uri.startsWith('at://')) {
-        throw new Error('ATURI must start with "at://"');
-    }
-    // check that all chars are boring ASCII
-    if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
-        throw new Error('Disallowed characters in ATURI (ASCII)');
-    }
-    const authorityEnd = uri.indexOf('/', 5);
-    const authority = authorityEnd === -1 ? uri.slice(5) : uri.slice(5, authorityEnd);
-    try {
-        (0, at_identifier_js_1.ensureValidAtIdentifier)(authority);
-    }
-    catch (cause) {
-        throw new Error('ATURI authority must be a valid handle or DID', { cause });
-    }
-    const collectionStart = authorityEnd === -1 ? -1 : authorityEnd + 1;
-    const collectionEnd = collectionStart === -1 ? -1 : uri.indexOf('/', collectionStart);
-    if (collectionStart !== -1) {
-        const collection = collectionEnd === -1
-            ? uri.slice(collectionStart)
-            : uri.slice(collectionStart, collectionEnd);
-        if (collection.length === 0) {
-            throw new Error('ATURI can not have a slash after authority without a path segment');
+    if (options?.strict !== false) {
+        if (groups.trailingSlash != null) {
+            return (0, result_js_1.failure)('ATURI can not have a trailing slash');
         }
-        if (!(0, nsid_js_1.isValidNsid)(collection)) {
-            throw new Error('ATURI requires first path segment (if supplied) to be valid NSID');
+        if (groups.query != null) {
+            return (0, result_js_1.failure)('ATURI query part is not allowed');
         }
-    }
-    const recordKeyStart = collectionEnd === -1 ? -1 : collectionEnd + 1;
-    const recordKeyEnd = recordKeyStart === -1 ? -1 : uri.indexOf('/', recordKeyStart);
-    if (recordKeyStart !== -1) {
-        if (recordKeyStart === uri.length) {
-            throw new Error('ATURI can not have a slash after collection, unless record key is provided');
+        if (groups.rkey != null && !(0, recordkey_js_1.isValidRecordKey)(groups.rkey)) {
+            return (0, result_js_1.failure)('ATURI has invalid record key');
         }
-        // would validate rkey here, but there are basically no constraints!
-    }
-    if (recordKeyEnd !== -1) {
-        throw new Error('ATURI path can have at most two parts, and no trailing slash');
     }
+    return (0, result_js_1.success)(groups);
 }
-function ensureValidAtUriRegex(input) {
-    // simple regex to enforce most constraints via just regex and length.
-    // hand wrote this regex based on above constraints. whew!
-    const aturiRegex = /^at:\/\/(?<authority>[a-zA-Z0-9._:%-]+)(\/(?<collection>[a-zA-Z0-9-.]+)(\/(?<rkey>[a-zA-Z0-9._~:@!$&%')(*+,;=-]+))?)?(#(?<fragment>\/[a-zA-Z0-9._~:@!$&%')(*+,;=\-[\]/\\]*))?$/;
-    const rm = input.match(aturiRegex);
-    if (!rm || !rm.groups) {
-        throw new Error("ATURI didn't validate via regex");
-    }
-    const groups = rm.groups;
-    try {
-        (0, handle_js_1.ensureValidHandleRegex)(groups.authority);
-    }
-    catch {
-        try {
-            (0, did_js_1.ensureValidDidRegex)(groups.authority);
-        }
-        catch {
-            throw new Error('ATURI authority must be a valid handle or DID');
-        }
-    }
-    if (groups.collection && !(0, nsid_js_1.isValidNsid)(groups.collection)) {
-        throw new Error('ATURI collection path segment must be a valid NSID');
-    }
-    if (input.length > 8 * 1024) {
-        throw new Error('ATURI is far too long');
-    }
+const BASIC_JSON_POINTER_REGEXP = /^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/;
+/**
+ * Checks if a string is a valid JSON pointer (RFC-6901) with the allowed chars
+ * for ATURI fragments. This is a very loose validation that only checks the
+ * basic syntax and charset.
+ */
+function parseJsonPointer(value, options) {
+    if (!BASIC_JSON_POINTER_REGEXP.test(value)) {
+        return (0, result_js_1.failure)('Invalid JSON pointer');
+    }
+    const result = parsePercentEncoding(value);
+    // In non-strict mode, we allow invalid percent-encoding in the fragment
+    if (!result.success && options?.strict === false) {
+        return (0, result_js_1.success)(value);
+    }
+    return result;
 }
-function isValidAtUri(input) {
+function parsePercentEncoding(value) {
     try {
-        ensureValidAtUri(input);
+        return (0, result_js_1.success)(decodeURIComponent(value));
     }
     catch {
-        return false;
+        // decodeURIComponent throws if the percent-encoding is invalid (e.g. "%FF")
+        return (0, result_js_1.failure)('Invalid percent-encoding');
     }
-    return true;
 }
 //# sourceMappingURL=aturi_validation.js.map