@dereekb/model 13.0.7 → 13.2.0

package/index.cjs.js

@@ -1,239 +1,217 @@
 'use strict';
 
 var util = require('@dereekb/util');
-var classTransformer = require('class-transformer');
-var classValidator = require('class-validator');
+var arktype = require('arktype');
 var makeError = require('make-error');
 
-/******************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
-
-
-function __decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-
-function __metadata(metadataKey, metadataValue) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
-}
-
-typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-};
-
+/**
+ * Maximum character length for address line fields (line1, line2).
+ */
 const ADDRESS_LINE_MAX_LENGTH = 50;
+/**
+ * Maximum character length for city names.
+ */
 const ADDRESS_CITY_MAX_LENGTH = 80;
+/**
+ * Maximum character length for full state names (e.g., "Texas").
+ */
 const ADDRESS_STATE_MAX_LENGTH = 30;
+/**
+ * Maximum character length for two-letter state codes (e.g., "TX").
+ */
 const ADDRESS_STATE_CODE_MAX_LENGTH = 2;
+/**
+ * Maximum character length for ZIP codes, accommodating ZIP+4 format (e.g., "77834-1234").
+ */
 const ADDRESS_ZIP_MAX_LENGTH = 11;
+/**
+ * Maximum character length for country names.
+ */
 const ADDRESS_COUNTRY_MAX_LENGTH = 80;
-class AbstractUnitedStatesAddressWithoutStateParams {
-    line1;
-    line2;
-    city;
-    zip;
-}
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.MaxLength(ADDRESS_LINE_MAX_LENGTH),
-    __metadata("design:type", String)
-], AbstractUnitedStatesAddressWithoutStateParams.prototype, "line1", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsOptional(),
-    classValidator.IsString(),
-    classValidator.MaxLength(ADDRESS_LINE_MAX_LENGTH),
-    __metadata("design:type", String)
-], AbstractUnitedStatesAddressWithoutStateParams.prototype, "line2", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.MaxLength(ADDRESS_CITY_MAX_LENGTH),
-    __metadata("design:type", String)
-], AbstractUnitedStatesAddressWithoutStateParams.prototype, "city", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.Matches(util.ZIP_CODE_STRING_REGEX),
-    classValidator.MaxLength(ADDRESS_ZIP_MAX_LENGTH),
-    __metadata("design:type", String)
-], AbstractUnitedStatesAddressWithoutStateParams.prototype, "zip", void 0);
-/**
- * UnitedStatesAddress that enforces a StateCode for the state value.
- */
-class UnitedStatesAddressWithStateCodeParams extends AbstractUnitedStatesAddressWithoutStateParams {
-    state;
-}
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.Matches(util.US_STATE_CODE_STRING_REGEX),
-    classValidator.MinLength(ADDRESS_STATE_CODE_MAX_LENGTH),
-    classValidator.MaxLength(ADDRESS_STATE_CODE_MAX_LENGTH),
-    __metadata("design:type", String)
-], UnitedStatesAddressWithStateCodeParams.prototype, "state", void 0);
-/**
- * UnitedStatesAddress that enforces a State for the state value.
- */
-class UnitedStatesAddressWithStateStringParams extends AbstractUnitedStatesAddressWithoutStateParams {
-    state;
-}
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.MaxLength(ADDRESS_STATE_MAX_LENGTH),
-    __metadata("design:type", String)
-], UnitedStatesAddressWithStateStringParams.prototype, "state", void 0);
+/**
+ * Base ArkType schema for United States address fields without the state.
+ */
+const baseUnitedStatesAddressType = arktype.type({
+    line1: `0 < string <= ${ADDRESS_LINE_MAX_LENGTH}`,
+    'line2?': `string <= ${ADDRESS_LINE_MAX_LENGTH}`,
+    city: `0 < string <= ${ADDRESS_CITY_MAX_LENGTH}`,
+    zip: [/^\d{5}(-\d{4})?$/, '&', `string <= ${ADDRESS_ZIP_MAX_LENGTH}`]
+});
+/**
+ * ArkType schema for a United States address with a two-letter state code (e.g., "TX").
+ */
+const unitedStatesAddressWithStateCodeType = baseUnitedStatesAddressType.merge({
+    state: [util.US_STATE_CODE_STRING_REGEX, '&', `${ADDRESS_STATE_CODE_MAX_LENGTH} <= string <= ${ADDRESS_STATE_CODE_MAX_LENGTH}`]
+});
+/**
+ * ArkType schema for a United States address with a full state name (e.g., "Texas").
+ */
+const unitedStatesAddressWithStateStringType = baseUnitedStatesAddressType.merge({
+    state: `0 < string <= ${ADDRESS_STATE_MAX_LENGTH}`
+});
 
+/**
+ * Fallback link type used when the actual type is not known.
+ */
 const UNKNOWN_WEBSITE_LINK_TYPE = 'u';
 /**
- * Max length of WebsiteLink's data type.
+ * Maximum character length for a {@link WebsiteLinkType} string.
  */
 const WEBSITE_LINK_TYPE_MAX_LENGTH = 32;
 /**
- * Alpha-numeric type between 1 and 32 characters only allowed.
+ * Regex pattern that validates a {@link WebsiteLinkType} as 1-32 alphanumeric characters.
  */
 const WEBSITE_LINK_TYPE_REGEX = /^[a-zA-Z0-9]{1,32}$/;
+/**
+ * Checks whether the given string is a valid {@link WebsiteLinkType}.
+ *
+ * @param input - the string to validate
+ * @returns true if it matches the alphanumeric 1-32 character pattern
+ *
+ * @example
+ * ```typescript
+ * isValidWebsiteLinkType('fb');    // true
+ * isValidWebsiteLinkType('');      // false
+ * isValidWebsiteLinkType('a-b');   // false (hyphen not allowed)
+ * ```
+ */
 function isValidWebsiteLinkType(input) {
     return WEBSITE_LINK_TYPE_REGEX.test(input);
 }
 /**
- * Default max length of WebsiteLink's data string.
+ * Maximum character length for the encoded data string in a {@link WebsiteLink}.
  */
 const WEBSITE_LINK_ENCODED_DATA_MAX_LENGTH = 1000;
-class WebsiteLink {
-    t;
-    d;
-    constructor(template) {
-        if (template != null) {
-            this.t = template.t;
-            this.d = template.d;
-        }
-    }
-}
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.Matches(WEBSITE_LINK_TYPE_REGEX),
-    classValidator.MaxLength(WEBSITE_LINK_TYPE_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteLink.prototype, "t", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.MaxLength(WEBSITE_LINK_ENCODED_DATA_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteLink.prototype, "d", void 0);
+/**
+ * ArkType schema for a {@link WebsiteLink}.
+ */
+const websiteLinkType = arktype.type({
+    t: [WEBSITE_LINK_TYPE_REGEX, '&', `0 < string <= ${WEBSITE_LINK_TYPE_MAX_LENGTH}`],
+    d: `0 < string <= ${WEBSITE_LINK_ENCODED_DATA_MAX_LENGTH}`
+});
 
 /**
- * Max length of WebsiteLink's data type.
+ * Maximum character length for a {@link WebsiteFileLinkType}. Matches {@link WEBSITE_LINK_TYPE_MAX_LENGTH}.
  */
 const WEBSITE_FILE_LINK_TYPE_MAX_LENGTH = WEBSITE_LINK_TYPE_MAX_LENGTH;
 /**
- * Has the same regex as WebsiteLinkType
+ * Validation regex for {@link WebsiteFileLinkType}. Matches {@link WEBSITE_LINK_TYPE_REGEX}.
  */
 const WEBSITE_FILE_LINK_TYPE_REGEX = WEBSITE_LINK_TYPE_REGEX;
 /**
- * Max length of WebsiteLink's data type.
+ * Maximum character length for a {@link WebsiteFileLinkMimeType}.
  */
 const WEBSITE_FILE_LINK_MIME_TYPE_MAX_LENGTH = 128;
 /**
- * Default max length of WebsiteLink's data string.
+ * Regex pattern that validates a MIME type string (e.g., "text/plain", "application/vnd.api+json").
  */
 const WEBSITE_FILE_LINK_MIME_TYPE_REGEX = /^\w+\/[-+.\w]+$/;
 /**
- * Max length of WebsiteLink's data type.
+ * Maximum character length for a {@link WebsiteFileLinkName}.
  */
 const WEBSITE_FILE_LINK_NAME_MAX_LENGTH = 128;
 /**
- * Max length of WebsiteLink's data type.
+ * Maximum character length for {@link WebsiteFileLinkData}, derived from the total encoded data budget
+ * minus the separator characters, type, MIME type, and name fields.
  */
 const WEBSITE_FILE_LINK_DATA_MAX_LENGTH = WEBSITE_LINK_ENCODED_DATA_MAX_LENGTH - 3 - WEBSITE_FILE_LINK_TYPE_MAX_LENGTH - WEBSITE_FILE_LINK_MIME_TYPE_MAX_LENGTH - WEBSITE_FILE_LINK_NAME_MAX_LENGTH;
+/**
+ * Regex pattern for file link data — disallows the pipe character since it is used as the encoding separator.
+ */
 const WEBSITE_FILE_LINK_DATA_REGEX = /^[^|]+$/;
-class WebsiteFileLink {
-    type;
-    mime;
-    name;
-    data;
-    constructor(template) {
-        if (template != null) {
-            this.type = template.type;
-            this.mime = template.mime;
-            this.name = template.name;
-            this.data = template.data;
-        }
-    }
-}
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsOptional(),
-    classValidator.IsString(),
-    classValidator.Matches(WEBSITE_FILE_LINK_TYPE_REGEX),
-    classValidator.MaxLength(WEBSITE_LINK_TYPE_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteFileLink.prototype, "type", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsOptional(),
-    classValidator.IsString(),
-    classValidator.Matches(WEBSITE_FILE_LINK_MIME_TYPE_REGEX),
-    classValidator.MaxLength(WEBSITE_FILE_LINK_MIME_TYPE_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteFileLink.prototype, "mime", void 0);
-__decorate([
-    classTransformer.Expose(),
-    classValidator.IsOptional(),
-    classValidator.IsString(),
-    classValidator.MaxLength(WEBSITE_FILE_LINK_NAME_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteFileLink.prototype, "name", void 0);
-__decorate([
-    classValidator.IsString(),
-    classValidator.IsNotEmpty(),
-    classValidator.Matches(WEBSITE_FILE_LINK_DATA_REGEX),
-    classValidator.MaxLength(WEBSITE_FILE_LINK_DATA_MAX_LENGTH),
-    __metadata("design:type", String)
-], WebsiteFileLink.prototype, "data", void 0);
+/**
+ * ArkType schema for a {@link WebsiteFileLink}.
+ */
+const websiteFileLinkType = arktype.type({
+    'type?': [WEBSITE_FILE_LINK_TYPE_REGEX, '&', `string <= ${WEBSITE_LINK_TYPE_MAX_LENGTH}`],
+    'mime?': [WEBSITE_FILE_LINK_MIME_TYPE_REGEX, '&', `string <= ${WEBSITE_FILE_LINK_MIME_TYPE_MAX_LENGTH}`],
+    'name?': `string <= ${WEBSITE_FILE_LINK_NAME_MAX_LENGTH}`,
+    data: [WEBSITE_FILE_LINK_DATA_REGEX, '&', `0 < string <= ${WEBSITE_FILE_LINK_DATA_MAX_LENGTH}`]
+});
+/**
+ * The {@link WebsiteLinkType} code used to identify a {@link WebsiteLink} as a file link.
+ */
 const WEBSITE_FILE_LINK_WEBSITE_LINK_TYPE = 'f';
+/**
+ * Converts a {@link WebsiteFileLink} to a {@link WebsiteLink} by encoding its fields into the data string.
+ *
+ * @param input - the file link to convert
+ * @returns a WebsiteLink with type "f" and pipe-encoded data
+ *
+ * @example
+ * ```typescript
+ * const fileLink: WebsiteFileLink = { type: 't', mime: 'text/plain', data: 'https://example.com/file.txt', name: 'file' };
+ * const link = websiteFileLinkToWebsiteLink(fileLink);
+ * // link.t === 'f'
+ * ```
+ */
 function websiteFileLinkToWebsiteLink(input) {
     return {
         t: WEBSITE_FILE_LINK_WEBSITE_LINK_TYPE,
         d: encodeWebsiteFileLinkToWebsiteLinkEncodedData(input)
     };
 }
+/**
+ * Converts a {@link WebsiteLink} back to a {@link WebsiteFileLink} by decoding the pipe-separated data string.
+ *
+ * @param input - a WebsiteLink whose data field contains an encoded file link
+ * @returns the decoded file link with type, MIME, name, and data fields
+ *
+ * @example
+ * ```typescript
+ * const link: WebsiteLink = { t: 'f', d: 't|text/plain|https://example.com/file.txt|file' };
+ * const fileLink = websiteLinkToWebsiteLinkFile(link);
+ * // fileLink.data === 'https://example.com/file.txt'
+ * ```
+ */
 function websiteLinkToWebsiteLinkFile(input) {
     const encodedData = input.d;
     return decodeWebsiteLinkEncodedDataToWebsiteFileLink(encodedData);
 }
+/**
+ * Separator character used when encoding/decoding file link fields into a single string.
+ */
 const WEBSITE_FILE_LINK_ENCODE_SEPARATOR = '|';
+/**
+ * Encodes a {@link WebsiteFileLink} into a pipe-separated string suitable for storage in a {@link WebsiteLink}'s data field.
+ *
+ * Fields are encoded in order: type, MIME, data, name. Empty/undefined fields become empty strings.
+ *
+ * @param input - the file link to encode
+ * @returns a pipe-separated encoded string
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeWebsiteFileLinkToWebsiteLinkEncodedData({
+ *   type: 't',
+ *   mime: 'test/test',
+ *   name: 'test-name',
+ *   data: 'https://example.com/'
+ * });
+ * // encoded === 't|test/test|https://example.com/|test-name'
+ * ```
+ */
 function encodeWebsiteFileLinkToWebsiteLinkEncodedData(input) {
     const encoded = [input.type, input.mime, input.data, input.name].map((x) => x || '').join(WEBSITE_FILE_LINK_ENCODE_SEPARATOR);
     return encoded;
 }
+/**
+ * Decodes a pipe-separated encoded string back into a {@link WebsiteFileLink}.
+ *
+ * Empty fields in the encoded string are omitted from the result (falsy values are filtered out).
+ *
+ * @param input - the pipe-separated encoded string
+ * @returns the decoded file link
+ *
+ * @example
+ * ```typescript
+ * const fileLink = decodeWebsiteLinkEncodedDataToWebsiteFileLink('t|test/test|https://example.com/|test-name');
+ * // fileLink.type === 't'
+ * // fileLink.mime === 'test/test'
+ * // fileLink.data === 'https://example.com/'
+ * // fileLink.name === 'test-name'
+ * ```
+ */
 function decodeWebsiteLinkEncodedDataToWebsiteFileLink(input) {
     const [type, mime, data, name] = util.splitJoinRemainder(input, WEBSITE_FILE_LINK_ENCODE_SEPARATOR, 4);
     return util.filterFalsyAndEmptyValues({
@@ -245,16 +223,40 @@ function decodeWebsiteLinkEncodedDataToWebsiteFileLink(input) {
 }
 
 /**
- * Used for isolating a username from a website that has the username as the base url.
+ * Isolates a username from a URL where the username is the first path segment after the domain.
+ *
+ * Strips trailing slashes and query parameters. Used by social platforms like Facebook, Instagram, and Twitter
+ * where the profile URL pattern is `https://domain.com/{username}`.
  *
- * Example:
- * - https://facebook.com/facebook
+ * @example
+ * ```typescript
+ * WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID('https://www.facebook.com/myuser');
+ * // returns 'myuser'
+ * ```
  */
 const WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID = util.isolateWebsitePathFunction({
     isolatePathComponents: 0,
     removeTrailingSlash: true,
     removeQueryParameters: true
 });
+/**
+ * Extracts a username from either a raw username string or a full profile URL where the username is the first path segment.
+ *
+ * Optionally prepends a prefix (e.g., "@" for TikTok, "$" for Cash App).
+ *
+ * @param input - a username or full profile URL
+ * @param prefix - optional prefix to prepend to the extracted username
+ * @returns the isolated username, optionally prefixed
+ *
+ * @example
+ * ```typescript
+ * usernameFromUsernameOrWebsiteWithBaseUrlUsername('https://facebook.com/myuser');
+ * // returns 'myuser'
+ *
+ * usernameFromUsernameOrWebsiteWithBaseUrlUsername('myuser', '@');
+ * // returns '@myuser'
+ * ```
+ */
 function usernameFromUsernameOrWebsiteWithBaseUrlUsername(input, prefix) {
     const username = util.toRelativeSlashPathStartType(WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID(usernameOrWebsiteUrlToWebsiteUrl(input)));
     if (prefix) {
@@ -264,14 +266,46 @@ function usernameFromUsernameOrWebsiteWithBaseUrlUsername(input, prefix) {
         return username;
     }
 }
+/**
+ * Extracts a username from either a raw username string or a full profile URL using a custom path isolation function.
+ *
+ * Used for platforms with non-standard URL patterns (e.g., Snapchat's `/add/{username}`, YouTube's `/c/{username}`).
+ *
+ * @param input - a username or full profile URL
+ * @param isolateFn - custom function that extracts the relevant path segment from the URL
+ * @returns the isolated username
+ */
 function usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input, isolateFn) {
     return util.toRelativeSlashPathStartType(isolateFn(usernameOrWebsiteUrlToWebsiteUrl(input)));
 }
+/**
+ * Normalizes a string that may be either a plain username or a full website URL into a consistent URL format.
+ *
+ * If the input has a website domain, it is returned as-is. Otherwise, it is treated as a path and converted to an absolute slash path.
+ *
+ * @param input - a username or website URL
+ * @returns a normalized website URL
+ */
 function usernameOrWebsiteUrlToWebsiteUrl(input) {
     return util.hasWebsiteDomain(input) ? input : util.toAbsoluteSlashPathStartType(util.removeHttpFromUrl(input));
 }
 // MARK: Website
+/**
+ * {@link WebsiteLinkType} code for generic website URLs.
+ */
 const WEBSITE_URL_WEBSITE_LINK_TYPE = 'w';
+/**
+ * Converts a generic website URL into a {@link WebsiteLink}, stripping the HTTP/HTTPS protocol.
+ *
+ * @param input - the full website URL
+ * @returns a WebsiteLink with the protocol removed from the data
+ *
+ * @example
+ * ```typescript
+ * const link = websiteUrlToWebsiteLink('https://example.com/page');
+ * // link.t === 'w', link.d === 'example.com/page'
+ * ```
+ */
 function websiteUrlToWebsiteLink(input) {
     return {
         t: WEBSITE_URL_WEBSITE_LINK_TYPE,
@@ -279,7 +313,16 @@ function websiteUrlToWebsiteLink(input) {
     };
 }
 // MARK: Email
+/**
+ * {@link WebsiteLinkType} code for email addresses.
+ */
 const EMAIL_URL_WEBSITE_LINK_TYPE = 'e';
+/**
+ * Converts an email address into a {@link WebsiteLink}.
+ *
+ * @param input - the email address
+ * @returns a WebsiteLink storing the email as data
+ */
 function emailAddressToWebsiteLink(input) {
     return {
         t: EMAIL_URL_WEBSITE_LINK_TYPE,
@@ -287,7 +330,16 @@ function emailAddressToWebsiteLink(input) {
     };
 }
 // MARK: Phone
+/**
+ * {@link WebsiteLinkType} code for phone numbers.
+ */
 const PHONE_URL_WEBSITE_LINK_TYPE = 'p';
+/**
+ * Converts an E.164 phone number into a {@link WebsiteLink}.
+ *
+ * @param input - the phone number in E.164 format
+ * @returns a WebsiteLink storing the phone number as data
+ */
 function phoneNumberToWebsiteLink(input) {
     return {
         t: PHONE_URL_WEBSITE_LINK_TYPE,
@@ -295,148 +347,325 @@ function phoneNumberToWebsiteLink(input) {
     };
 }
 // MARK: Facebook
+/** Base URL for Facebook profiles. */
 const FACEBOOK_BASE_URL = `https://www.facebook.com`;
+/** {@link WebsiteLinkType} code for Facebook. */
 const FACEBOOK_WEBSITE_LINK_TYPE = 'fb';
+/**
+ * Converts a Facebook profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Accepts either a raw username or a full Facebook profile URL.
+ *
+ * @param input - a Facebook profile ID or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ *
+ * @example
+ * ```typescript
+ * facebookProfileUrlToWebsiteLink('https://www.facebook.com/myuser');
+ * // { t: 'fb', d: 'myuser' }
+ *
+ * facebookProfileUrlToWebsiteLink('myuser');
+ * // { t: 'fb', d: 'myuser' }
+ * ```
+ */
 function facebookProfileUrlToWebsiteLink(input) {
     return {
         t: FACEBOOK_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input)
     };
 }
+/**
+ * Constructs a full Facebook profile URL from a profile ID.
+ *
+ * @param profileId - the Facebook profile ID or username
+ * @returns the full profile URL
+ */
 function facebookProfileUrl(profileId) {
     return `${FACEBOOK_BASE_URL}/${profileId}`;
 }
 // MARK: Instagram
+/** Base URL for Instagram profiles. */
 const INSTAGRAM_BASE_URL = `https://www.instagram.com`;
+/** {@link WebsiteLinkType} code for Instagram. */
 const INSTAGRAM_WEBSITE_LINK_TYPE = 'ig';
+/**
+ * Converts an Instagram profile ID or URL into a {@link WebsiteLink}.
+ *
+ * @param input - an Instagram username or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function instagramProfileUrlToWebsiteLink(input) {
     return {
         t: INSTAGRAM_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input)
     };
 }
+/**
+ * Constructs a full Instagram profile URL from a profile ID.
+ *
+ * @param profileId - the Instagram username
+ * @returns the full profile URL
+ */
 function instagramProfileUrl(profileId) {
     return `${INSTAGRAM_BASE_URL}/${profileId}`;
 }
 // MARK: Twitter
+/** Base URL for Twitter profiles. */
 const TWITTER_BASE_URL = `https://www.twitter.com`;
+/** {@link WebsiteLinkType} code for Twitter. */
 const TWITTER_WEBSITE_LINK_TYPE = 'tw';
+/**
+ * Converts a Twitter profile ID or URL into a {@link WebsiteLink}.
+ *
+ * @param input - a Twitter username or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function twitterProfileUrlToWebsiteLink(input) {
     return {
         t: TWITTER_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input)
     };
 }
+/**
+ * Constructs a full Twitter profile URL from a profile ID.
+ *
+ * @param profileId - the Twitter username
+ * @returns the full profile URL
+ */
 function twitterProfileUrl(profileId) {
     return `${TWITTER_BASE_URL}/${profileId}`;
 }
 // MARK: Tiktok
+/** Base URL for TikTok profiles. */
 const TIKTOK_BASE_URL = `https://tiktok.com`;
+/** TikTok usernames are prefixed with "@" in URLs and stored data. */
 const TIKTOK_USERNAME_PREFIX = '@';
+/** {@link WebsiteLinkType} code for TikTok. */
 const TIKTOK_WEBSITE_LINK_TYPE = 'tt';
+/**
+ * Converts a TikTok profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Automatically prepends the "@" prefix if not already present.
+ *
+ * @param input - a TikTok username (with or without "@") or full profile URL
+ * @returns a WebsiteLink with the "@"-prefixed username as data
+ */
 function tiktokProfileUrlToWebsiteLink(input) {
     return {
         t: TIKTOK_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input, TIKTOK_USERNAME_PREFIX)
     };
 }
+/**
+ * Constructs a full TikTok profile URL from a profile ID.
+ *
+ * @param profileId - the TikTok username (without "@" prefix)
+ * @returns the full profile URL with "@" prefix
+ */
 function tiktokProfileUrl(profileId) {
     return `${TIKTOK_BASE_URL}/@${profileId}`;
 }
 // MARK: Snapchat
+/** Base URL for Snapchat profiles. */
 const SNAPCHAT_BASE_URL = `https://snapchat.com`;
+/** {@link WebsiteLinkType} code for Snapchat. */
 const SNAPCHAT_WEBSITE_LINK_TYPE = 'sc';
+/**
+ * Isolates a Snapchat username from a URL, ignoring the `/add/` base path segment.
+ */
 const SNAPCHAT_WEBSITE_LINK_ISOLATE_PROFILE_ID = util.isolateWebsitePathFunction({
     ignoredBasePath: 'add',
     isolatePathComponents: 0,
     removeTrailingSlash: true,
     removeQueryParameters: true
 });
+/**
+ * Converts a Snapchat profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Handles Snapchat's `/add/{username}` URL pattern.
+ *
+ * @param input - a Snapchat username or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function snapchatProfileUrlToWebsiteLink(input) {
     return {
         t: SNAPCHAT_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input, SNAPCHAT_WEBSITE_LINK_ISOLATE_PROFILE_ID)
     };
 }
+/**
+ * Constructs a full Snapchat profile URL from a profile ID.
+ *
+ * @param profileId - the Snapchat username
+ * @returns the full profile URL with `/add/` path
+ */
 function snapchatProfileUrl(profileId) {
     return `${SNAPCHAT_BASE_URL}/add/${profileId}`;
 }
 // MARK: YouTube
+/** Base URL for YouTube channels. */
 const YOUTUBE_BASE_URL = `https://youtube.com`;
+/** {@link WebsiteLinkType} code for YouTube. */
 const YOUTUBE_WEBSITE_LINK_TYPE = 'yt';
+/**
+ * Isolates a YouTube channel name from a URL, ignoring the `/c/` base path segment.
+ */
 const YOUTUBE_WEBSITE_LINK_ISOLATE_PROFILE_ID = util.isolateWebsitePathFunction({
     ignoredBasePath: 'c',
     isolatePathComponents: 0,
     removeTrailingSlash: true,
     removeQueryParameters: true
 });
+/**
+ * Converts a YouTube channel ID or URL into a {@link WebsiteLink}.
+ *
+ * Handles YouTube's `/c/{channel}` URL pattern.
+ *
+ * @param input - a YouTube channel name or full channel URL
+ * @returns a WebsiteLink with the isolated channel name as data
+ */
 function youtubeProfileUrlToWebsiteLink(input) {
     return {
         t: YOUTUBE_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input, YOUTUBE_WEBSITE_LINK_ISOLATE_PROFILE_ID)
     };
 }
+/**
+ * Constructs a full YouTube channel URL from a profile ID.
+ *
+ * @param profileId - the YouTube channel name
+ * @returns the full channel URL with `/c/` path
+ */
 function youtubeProfileUrl(profileId) {
     return `${YOUTUBE_BASE_URL}/c/${profileId}`;
 }
 // MARK: PayPal
+/** Base URL for PayPal.me profiles. */
 const PAYPAL_BASE_URL = `https://paypal.me`;
+/** {@link WebsiteLinkType} code for PayPal. */
 const PAYPAL_WEBSITE_LINK_TYPE = 'pp';
+/**
+ * Converts a PayPal profile ID or URL into a {@link WebsiteLink}.
+ *
+ * @param input - a PayPal username or full PayPal.me URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function paypalProfileUrlToWebsiteLink(input) {
     return {
         t: PAYPAL_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input)
     };
 }
+/**
+ * Constructs a full PayPal.me profile URL from a profile ID.
+ *
+ * @param profileId - the PayPal username
+ * @returns the full PayPal.me URL
+ */
 function paypalProfileUrl(profileId) {
     return `${PAYPAL_BASE_URL}/${profileId}`;
 }
 // MARK: Cashapp
+/** Base URL for Cash App profiles. */
 const CASHAPP_BASE_URL = `https://cash.app`;
+/** Cash App usernames are prefixed with "$" (cashtag). */
 const CASHAPP_USERNAME_PREFIX = '$';
+/** {@link WebsiteLinkType} code for Cash App. */
 const CASHAPP_WEBSITE_LINK_TYPE = 'ca';
+/**
+ * Converts a Cash App profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Automatically prepends the "$" prefix if not already present.
+ *
+ * @param input - a Cash App username (with or without "$") or full profile URL
+ * @returns a WebsiteLink with the "$"-prefixed username as data
+ */
 function cashappProfileUrlToWebsiteLink(input) {
     return {
         t: CASHAPP_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithBaseUrlUsername(input, CASHAPP_USERNAME_PREFIX)
     };
 }
+/**
+ * Constructs a full Cash App profile URL from a profile ID.
+ *
+ * @param profileId - the Cash App username (without "$" prefix)
+ * @returns the full Cash App URL with "$" prefix
+ */
 function cashappProfileUrl(profileId) {
     return `${CASHAPP_BASE_URL}/$${profileId}`;
 }
 // MARK: Venmo
+/** Base URL for Venmo profiles. */
 const VENMO_BASE_URL = `https://account.venmo.com`;
+/** {@link WebsiteLinkType} code for Venmo. */
 const VENMO_WEBSITE_LINK_TYPE = 'vn';
+/**
+ * Isolates a Venmo username from a URL, ignoring the `/u/` base path segment.
+ */
 const VENMO_WEBSITE_LINK_ISOLATE_PROFILE_ID = util.isolateWebsitePathFunction({
     ignoredBasePath: 'u',
     isolatePathComponents: 0,
     removeTrailingSlash: true,
     removeQueryParameters: true
 });
+/**
+ * Converts a Venmo profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Handles Venmo's `/u/{username}` URL pattern.
+ *
+ * @param input - a Venmo username or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function venmoProfileUrlToWebsiteLink(input) {
     return {
         t: VENMO_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input, VENMO_WEBSITE_LINK_ISOLATE_PROFILE_ID)
     };
 }
+/**
+ * Constructs a full Venmo profile URL from a profile ID.
+ *
+ * @param profileId - the Venmo username
+ * @returns the full profile URL with `/u/` path
+ */
 function venmoProfileUrl(profileId) {
     return `${VENMO_BASE_URL}/u/${profileId}`;
 }
 // MARK: Spotify
+/** Base URL for Spotify profiles. */
 const SPOTIFY_BASE_URL = `https://open.spotify.com/`;
+/** {@link WebsiteLinkType} code for Spotify. */
 const SPOTIFY_WEBSITE_LINK_TYPE = 'sp';
+/**
+ * Isolates a Spotify username from a URL, ignoring the `/user/` base path segment.
+ */
 const SPOTIFY_WEBSITE_LINK_ISOLATE_PROFILE_ID = util.isolateWebsitePathFunction({
     ignoredBasePath: 'user',
     isolatePathComponents: 0,
     removeTrailingSlash: true,
     removeQueryParameters: true
 });
+/**
+ * Converts a Spotify profile ID or URL into a {@link WebsiteLink}.
+ *
+ * Handles Spotify's `/user/{username}` URL pattern.
+ *
+ * @param input - a Spotify username or full profile URL
+ * @returns a WebsiteLink with the isolated username as data
+ */
 function spotifyProfileUrlToWebsiteLink(input) {
     return {
         t: SPOTIFY_WEBSITE_LINK_TYPE,
         d: usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input, SPOTIFY_WEBSITE_LINK_ISOLATE_PROFILE_ID)
     };
 }
+/**
+ * Constructs a full Spotify profile URL from a profile ID.
+ *
+ * @param profileId - the Spotify username
+ * @returns the full profile URL with `/user/` path
+ */
 function spotifyProfileUrl(profileId) {
     return `${SPOTIFY_BASE_URL}/user/${profileId}`;
 }
@@ -445,10 +674,17 @@ const GRANTED_SYS_ADMIN_ROLE_KEY = 'sysadmin';
 const GRANTED_OWNER_ROLE_KEY = 'owner';
 const GRANTED_ADMIN_ROLE_KEY = 'admin';
 /**
- * Returns true if the input role is a GrantedAdminRole or a GrantedOwnerRole.
+ * Checks whether the given role represents an admin-level permission (either "admin" or "owner").
  *
- * @param role
- * @returns
+ * @param role - the role to check
+ * @returns true if the role is an admin or owner role
+ *
+ * @example
+ * ```typescript
+ * isGrantedAdminLevelRole('admin');  // true
+ * isGrantedAdminLevelRole('owner');  // true
+ * isGrantedAdminLevelRole('read');   // false
+ * ```
  */
 function isGrantedAdminLevelRole(role) {
     return role === GRANTED_ADMIN_ROLE_KEY || role === GRANTED_OWNER_ROLE_KEY;
@@ -458,27 +694,75 @@ const GRANTED_UPDATE_ROLE_KEY = 'update';
 const GRANTED_DELETE_ROLE_KEY = 'delete';
 const FULL_ACCESS_ROLE_KEY = '__FULL__';
 const NO_ACCESS_ROLE_KEY = '__EMPTY__';
+/**
+ * Creates a {@link GrantedRoleMap} that explicitly denies all access.
+ *
+ * @returns a role map with only the no-access marker set
+ *
+ * @example
+ * ```typescript
+ * const map = noAccessRoleMap();
+ * isNoAccessRoleMap(map); // true
+ * ```
+ */
 function noAccessRoleMap() {
     return {
         [NO_ACCESS_ROLE_KEY]: true
     };
 }
+/**
+ * Type guard that checks whether a role map is a no-access map.
+ *
+ * @param input - the role map to check
+ * @returns true if the map has the no-access marker
+ */
 function isNoAccessRoleMap(input) {
     return input[NO_ACCESS_ROLE_KEY] === true;
 }
+/**
+ * Creates a {@link GrantedRoleMap} that grants full access to all roles.
+ *
+ * @returns a role map with the full-access marker set
+ *
+ * @example
+ * ```typescript
+ * const map = fullAccessRoleMap();
+ * isFullAccessRoleMap(map); // true
+ * ```
+ */
 function fullAccessRoleMap() {
     return {
         [FULL_ACCESS_ROLE_KEY]: true
     };
 }
+/**
+ * Type guard that checks whether a role map is a full-access map.
+ *
+ * @param input - the role map to check
+ * @returns true if the map has the full-access marker
+ */
 function isFullAccessRoleMap(input) {
     return input[FULL_ACCESS_ROLE_KEY] === true;
 }
 /**
- * Creates a GrantedRoleMapReader.
+ * Creates a {@link GrantedRoleMapReader} for querying granted roles from a role map.
  *
- * @param map
- * @returns
+ * The reader handles full-access and no-access maps as special cases, and provides methods
+ * for checking individual roles or sets of roles.
+ *
+ * @param map - the granted role map to read from
+ * @returns a reader instance for querying the map
+ *
+ * @example
+ * ```typescript
+ * const roleMap: GrantedRoleMap = { read: true, first: true };
+ * const reader = grantedRoleMapReader(roleMap);
+ *
+ * reader.hasRole('read');                   // true
+ * reader.hasRole('delete');                 // false
+ * reader.containsRoles('any', ['read']);    // true
+ * reader.containsRoles('all', ['read', 'delete']); // false
+ * ```
  */
 function grantedRoleMapReader(map) {
     return new GrantedRoleMapReaderInstance(map);
@@ -540,21 +824,62 @@ class GrantedRoleMapReaderInstance {
     }
 }
 /**
- * Converts the input array of roles to a GrantedRoleKeysMap.
+ * Converts an array of role strings into a {@link GrantedRoleKeysMap} where each role is mapped to the given boolean value.
  *
- * @param roles
- * @returns
+ * @param roles - the role strings to include
+ * @param value - the boolean value to assign to each role (defaults to true)
+ * @returns a map of roles to boolean values
+ *
+ * @example
+ * ```typescript
+ * const map = grantedRoleKeysMapFromArray(['read', 'update']);
+ * // { read: true, update: true }
+ * ```
  */
 function grantedRoleKeysMapFromArray(roles, value = true) {
     return util.arrayToObject(roles, (x) => x, () => value);
 }
 
+/**
+ * Creates a {@link ContextGrantedModelRoles} with a no-access role map, indicating the context has no permissions.
+ *
+ * @param context - the context that was evaluated
+ * @param data - optional model data, if it was loaded
+ * @returns a ContextGrantedModelRoles with no access
+ *
+ * @example
+ * ```typescript
+ * const result = noAccessContextGrantedModelRoles(userContext);
+ * // result.roleMap contains the no-access marker
+ * ```
+ */
 function noAccessContextGrantedModelRoles(context, data) {
     return contextGrantedModelRoles(context, data, noAccessRoleMap());
 }
+/**
+ * Creates a {@link ContextGrantedModelRoles} with a full-access role map, granting all permissions.
+ *
+ * @param context - the context that was evaluated
+ * @param data - optional model data
+ * @returns a ContextGrantedModelRoles with full access
+ *
+ * @example
+ * ```typescript
+ * const result = fullAccessGrantedModelRoles(adminContext, modelData);
+ * // result.roleMap contains the full-access marker
+ * ```
+ */
 function fullAccessGrantedModelRoles(context, data) {
     return contextGrantedModelRoles(context, data, fullAccessRoleMap());
 }
+/**
+ * Creates a {@link ContextGrantedModelRoles} with the given role map, data, and context.
+ *
+ * @param context - the context that was evaluated
+ * @param data - the model data, if loaded
+ * @param roles - the granted role map
+ * @returns a ContextGrantedModelRoles combining all inputs
+ */
 function contextGrantedModelRoles(context, data, roles) {
     return {
         data,
@@ -605,6 +930,22 @@ class AbstractModelPermissionService {
     }
 }
 
+/**
+ * Creates a factory that normalizes a {@link SyncEntityCommonTypeIdPairFactoryInput} into a full {@link SyncEntityCommonTypeIdPair}.
+ *
+ * If the input is a string, it is treated as a commonId and paired with the given commonType.
+ * If the input is already a pair, it is returned as-is.
+ *
+ * @param commonType - the default common type to use when input is a plain string
+ * @returns a factory function that produces SyncEntityCommonTypeIdPair instances
+ *
+ * @example
+ * ```typescript
+ * const factory = syncEntityCommonTypeIdPairFactory('user');
+ * factory('abc123');  // { commonType: 'user', commonId: 'abc123' }
+ * factory({ commonType: 'user', commonId: 'abc123' });  // passed through as-is
+ * ```
+ */
 function syncEntityCommonTypeIdPairFactory(commonType) {
     return (input) => {
         if (typeof input === 'string') {
@@ -619,10 +960,23 @@ function syncEntityCommonTypeIdPairFactory(commonType) {
     };
 }
 /**
- * Creates a SyncEntityFactory.
+ * Creates a {@link SyncEntityFactory} that produces {@link SyncEntity} instances from a common type/id pair.
  *
- * @param config
- * @returns
+ * The factory attaches the configured source info and optionally transforms the commonId into an entity id
+ * using the provided idFactory (defaults to identity).
+ *
+ * @param config - source info and optional id factory
+ * @returns a factory that creates SyncEntity instances
+ *
+ * @example
+ * ```typescript
+ * const factory = syncEntityFactory({
+ *   sourceInfo: { id: 'api', name: 'External API' }
+ * });
+ *
+ * const entity = factory({ commonType: 'user', commonId: 'abc123' });
+ * // entity.id === 'abc123', entity.sourceInfo.id === 'api'
+ * ```
  */
 function syncEntityFactory(config) {
     const { idFactory: inputIdFactory, sourceInfo } = config;
@@ -682,6 +1036,26 @@ class SynchronizationFailedError extends makeError.BaseError {
     }
 }
 
+/**
+ * Creates a {@link SyncEntitySynchronizer} from the given configuration.
+ *
+ * Registers common type synchronizers and provides lookup by common type. Throws
+ * {@link UnregisteredSyncEntityCommonTypeError} if an unregistered common type is requested.
+ *
+ * @param config - contains the list of common type synchronizers to register
+ * @returns a synchronizer that delegates to the appropriate common type synchronizer
+ * @throws {UnregisteredSyncEntityCommonTypeError} when requesting an unregistered common type
+ *
+ * @example
+ * ```typescript
+ * const synchronizer = syncEntitySynchronizer({
+ *   commonTypeSynchronizers: [userSynchronizer, orderSynchronizer]
+ * });
+ *
+ * const instance = await synchronizer.synchronizeInstance({ commonType: 'user', commonId: '123' });
+ * const result = await instance.synchronize();
+ * ```
+ */
 function syncEntitySynchronizer(config) {
     const map = new Map(config.commonTypeSynchronizers.map((x) => [x.commonType, x]));
     const commonTypes = Array.from(map.keys());
@@ -702,6 +1076,21 @@ function syncEntitySynchronizer(config) {
     };
 }
 
+/**
+ * Creates a {@link BasicSyncEntityCommonTypeSynchronizer} that orchestrates synchronization across multiple sources
+ * for a specific entity common type.
+ *
+ * The synchronizer follows a primary/secondary/replica flow:
+ * 1. The primary source is synchronized first (exactly one required).
+ * 2. Secondary sources are synchronized sequentially; if a secondary reports deletion while primary did not, the sync restarts once.
+ * 3. Replica sources are synchronized concurrently (up to 3 in parallel).
+ *
+ * @param config - common type, sources, and context loader
+ * @returns a synchronizer for the configured common type
+ * @throws {NoPrimarySyncSourceError} when no primary source is found
+ * @throws {MultiplePrimarySyncSourceError} when more than one primary source is found
+ * @throws {SynchronizationFailedError} when primary or secondary sync returns failed/error
+ */
 function basicSyncEntityCommonTypeSynchronizerInstanceFactory(config) {
     const { commonType, sources, entitySourceContextLoader, dynamicSources = false } = config;
     const syncEntityCommonTypeIdPairForType = syncEntityCommonTypeIdPairFactory(commonType);
@@ -895,111 +1284,114 @@ function basicSyncEntityCommonTypeSynchronizerInstanceFactory(config) {
     return result;
 }
 
-// MARK: String
-function transformStringToBoolean(defaultValue) {
-    return (params) => util.stringToBoolean(params.value, defaultValue);
-}
-// MARK: Comma Separated Values
-function transformCommaSeparatedValueToArray(mapFn) {
-    return (params) => {
-        let result;
-        if (params.value) {
-            if (Array.isArray(params.value)) {
-                result = params.value;
-            }
-            else {
-                result = util.splitCommaSeparatedString(params.value, mapFn);
-            }
-        }
-        return result;
-    };
-}
-const transformCommaSeparatedNumberValueToArray = transformCommaSeparatedValueToArray((x) => Number(x));
-const transformCommaSeparatedStringValueToArray = transformCommaSeparatedValueToArray((x) => x);
-
-// MARK: Transform Annotations
-function TransformCommaSeparatedValueToArray(mapFn) {
-    return classTransformer.Transform(transformCommaSeparatedValueToArray(mapFn));
-}
-const TransformCommaSeparatedStringValueToArray = () => classTransformer.Transform(transformCommaSeparatedStringValueToArray);
-const TransformCommaSeparatedNumberValueToArray = () => classTransformer.Transform(transformCommaSeparatedNumberValueToArray);
-const TransformStringValueToBoolean = () => classTransformer.Transform(transformStringToBoolean());
-
+/**
+ * Creates a function that validates input against an ArkType schema and then processes it.
+ *
+ * On validation success, calls the configured handler function. On validation failure, delegates to the error handler.
+ *
+ * @param config - schema, handler function, and validation error handler
+ * @returns a function that validates and processes input objects
+ *
+ * @example
+ * ```typescript
+ * const processUser = transformAndValidateObject({
+ *   schema: userType,
+ *   fn: async (user) => ({ id: user.id }),
+ *   handleValidationError: async (errors) => { throw new Error(errors.summary); }
+ * });
+ *
+ * const result = await processUser({ id: '123', name: 'John' });
+ * ```
+ */
 function transformAndValidateObject(config) {
     const transformToResult = transformAndValidateObjectResult(config);
     const { handleValidationError } = config;
-    return (input, context) => transformToResult(input, context).then(async (x) => {
-        const object = x.object;
-        let result;
+    return async (input, context) => {
+        const x = await transformToResult(input, context);
         if (x.success) {
-            result = x.result;
-        }
-        else {
-            result = await handleValidationError(x.validationErrors);
+            return { object: x.object, result: x.result };
         }
-        return {
-            object,
-            result
-        };
-    });
+        // Error handler is expected to throw. If it doesn't, there is no validated object to return.
+        const result = await handleValidationError(x.validationErrors);
+        return { object: undefined, result };
+    };
 }
 /**
- * Creates a new TransformAndValidateObjectFactory.
+ * Creates a reusable factory for generating transform-and-validate functions with shared defaults.
+ *
+ * The factory pre-configures error handling so individual function calls
+ * only need to specify the schema and handler.
  *
- * @param defaults
- * @returns
+ * @param defaults - default error handler
+ * @returns a factory function that creates TransformAndValidateObjectFunction instances
  */
 function transformAndValidateObjectFactory(defaults) {
-    const { handleValidationError: defaultHandleValidationError, optionsForContext, defaultValidationOptions } = defaults;
-    return (classType, fn, handleValidationError) => {
+    const { handleValidationError: defaultHandleValidationError } = defaults;
+    return (schema, fn, handleValidationError) => {
         const config = {
-            classType,
+            schema,
             fn,
-            handleValidationError: handleValidationError ?? defaultHandleValidationError,
-            optionsForContext,
-            defaultValidationOptions
+            handleValidationError: handleValidationError ?? defaultHandleValidationError
         };
         return transformAndValidateObject(config);
     };
 }
 /**
- * Factory function that wraps the input class type and handler function to first transform the input object to a the given class, and then validate it.
+ * Creates a function that validates input against an ArkType schema and returns a discriminated result.
  *
- * @param classType
- * @param fn
- * @returns
+ * Returns `{ success: true, object, result }` on valid input, or `{ success: false, validationErrors }` on failure.
+ * The caller is responsible for handling the error case.
+ *
+ * @param config - schema and handler function
+ * @returns a function that returns a success/error discriminated result
+ *
+ * @example
+ * ```typescript
+ * const validateUser = transformAndValidateObjectResult({
+ *   schema: userType,
+ *   fn: async (user) => ({ saved: true })
+ * });
+ *
+ * const result = await validateUser({ name: 'John' });
+ * if (result.success) {
+ *   console.log(result.result);
+ * } else {
+ *   console.log(result.validationErrors.summary);
+ * }
+ * ```
  */
 function transformAndValidateObjectResult(config) {
-    const { defaultValidationOptions, classType, fn, optionsForContext: inputOptionsForContext } = config;
-    const optionsForContext = inputOptionsForContext ?? (() => ({}));
-    return async (input, context) => {
-        const { transform: transformOptions, validate: validateOptions } = optionsForContext(context);
-        const object = classTransformer.plainToInstance(classType, input, {
-            ...transformOptions,
-            // Note: Each variable on the target class must be marked with the @Expose() annotation.
-            excludeExtraneousValues: true
-        });
-        const validationErrors = await classValidator.validate(object, {
-            forbidUnknownValues: false, // allow classes without annotations by default
-            ...defaultValidationOptions,
-            ...validateOptions
-        });
-        if (validationErrors.length) {
-            return { object, validationErrors, success: false };
-        }
-        else {
-            const result = await fn(object);
-            return { object, result, success: true };
+    const { schema, fn } = config;
+    return async (input) => {
+        const out = schema(input);
+        if (out instanceof arktype.type.errors) {
+            return { validationErrors: out, success: false };
         }
+        const object = out;
+        const result = await fn(object);
+        return { object, result, success: true };
     };
 }
 
+/**
+ * Creates a factory for transform-and-validate functions that return the result with the parsed object attached as `params`.
+ *
+ * @param defaults - shared error handler defaults
+ * @returns a factory that produces functions returning {@link TransformAndValidateFunctionResult}
+ */
 function transformAndValidateFunctionResultFactory(defaults) {
     return toTransformAndValidateFunctionResultFactory(transformAndValidateObjectFactory(defaults));
 }
+/**
+ * Wraps an existing {@link TransformAndValidateObjectFactory} to produce functions that attach the parsed object
+ * as `params` on the result.
+ *
+ * @param transformAndValidateObjectFactory - the base factory to wrap
+ * @returns a factory that produces functions returning results with `params` attached
+ */
 function toTransformAndValidateFunctionResultFactory(transformAndValidateObjectFactory) {
-    return (classType, fn, handleValidationError) => {
-        const transformAndValidateObjectFn = transformAndValidateObjectFactory(classType, fn, handleValidationError);
+    return (schema, fn, handleValidationError) => {
+        const transformAndValidateObjectFn = transformAndValidateObjectFactory(schema, fn, handleValidationError);
         return (input, context) => {
             return toTransformAndValidateFunctionResult(transformAndValidateObjectFn(input, context));
         };
@@ -1014,10 +1406,18 @@ function toTransformAndValidateFunctionResult(objectOutput) {
     });
 }
 
+/**
+ * Creates a factory for transform-and-validate functions that return only the result (discarding the parsed object).
+ *
+ * Useful when you only need the processed output and don't need access to the validated input.
+ *
+ * @param defaults - shared error handler defaults
+ * @returns a factory that produces functions returning only the handler's result
+ */
 function transformAndValidateResultFactory(defaults) {
     const factory = transformAndValidateObjectFactory(defaults);
-    return (classType, fn, handleValidationError) => {
-        const transformAndValidateObjectFn = factory(classType, fn, handleValidationError);
+    return (schema, fn, handleValidationError) => {
+        const transformAndValidateObjectFn = factory(schema, fn, handleValidationError);
         return async (input, context) => {
             const { result } = await transformAndValidateObjectFn(input, context);
             return result;
@@ -1026,152 +1426,80 @@ function transformAndValidateResultFactory(defaults) {
 }
 
 /**
- * isISO8601DayString validator
- */
-function IsISO8601DayString(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isISO8601DayString',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: util.isISO8601DayString,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a ISO8601DayString.`, validationOptions)
-            }
-        });
-    };
+ * ArkType schema for a model key (non-empty string).
+ */
+const modelKeyType = arktype.type('string > 0');
+/**
+ * ArkType schema for a model id (non-empty string).
+ */
+const modelIdType = arktype.type('string > 0');
+/**
+ * ArkType schema for target model params with a required `key` field.
+ */
+const targetModelParamsType = arktype.type({
+    key: modelKeyType
+});
+/**
+ * ArkType schema for target model id params with a required `id` field.
+ */
+const targetModelIdParamsType = arktype.type({
+    id: modelIdType
+});
+
+function clearable(definition) {
+    if (typeof definition === 'string') {
+        return `${definition} | null | undefined`;
+    }
+    return definition.or('null').or('undefined');
 }
 
 /**
- * isMinuteOfDay validator
- */
-function IsMinuteOfDay(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isMinuteOfDay',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: util.isMinuteOfDay,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a valid minute of the day.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid ISO 8601 day string (e.g., "2024-01-15").
+ */
+const iso8601DayStringType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isISO8601DayString(val)) || ctx.mustBe('a valid ISO 8601 day string'));
 
 /**
- * isE164PhoneNumber validator that does not allowed extensions.
- */
-function IsE164PhoneNumber(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isE164PhoneNumber',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: (x) => util.isE164PhoneNumber(x, false),
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a E164PhoneNumber with no extension.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid minute of the day (0-1439).
+ */
+const minuteOfDayType = arktype.type('number').narrow((val, ctx) => (val != null && util.isMinuteOfDay(val)) || ctx.mustBe('a valid minute of the day (0-1439)'));
+
 /**
- * isE164PhoneNumber validator that allows extensions.
- *
- * @param validationOptions
- * @returns
- */
-function IsE164PhoneNumberWithOptionalExtension(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isE164PhoneNumber',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: (x) => util.isE164PhoneNumber(x, true),
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not an E164PhoneNumber or has an invalid extension.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid E.164 phone number without an extension.
+ */
+const e164PhoneNumberType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isE164PhoneNumber(val, false)) || ctx.mustBe('a valid E.164 phone number without an extension'));
 /**
- * isE164PhoneNumberWithExtension validator
- *
- * @param validationOptions
- * @returns
- */
-function IsE164PhoneNumberWithExtension(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isE164PhoneNumberWithExtension',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: util.isE164PhoneNumberWithExtension,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a E164PhoneNumberWithExtension.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid E.164 phone number, optionally with an extension.
+ */
+const e164PhoneNumberWithOptionalExtensionType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isE164PhoneNumber(val, true)) || ctx.mustBe('a valid E.164 phone number'));
+/**
+ * ArkType schema for a valid E.164 phone number that includes an extension.
+ */
+const e164PhoneNumberWithExtensionType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isE164PhoneNumberWithExtension(val)) || ctx.mustBe('a valid E.164 phone number with an extension'));
 
 /**
- * isUniqueKeyedFunction validator
+ * Creates an ArkType schema that validates an array has no duplicate keys.
+ *
+ * @param readKey - function that extracts the key from each array element
+ * @returns an ArkType schema that narrows `T[]` to ensure uniqueness
+ *
+ * @example
+ * ```typescript
+ * const uniqueItemsType = uniqueKeyedType((item: Item) => item.id);
+ * ```
  */
-function IsUniqueKeyed(readKey, validationOptions) {
+function uniqueKeyedType(readKey) {
     const isUniqueKeyed = util.isUniqueKeyedFunction(readKey);
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isUniqueKeyed',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: isUniqueKeyed,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value has one or more values with the same key. Keys must be unique.`, validationOptions)
-            }
-        });
-    };
+    return arktype.type('unknown[]').narrow((val, ctx) => (val != null && isUniqueKeyed(val)) || ctx.mustBe('an array with unique keys'));
 }
 
 /**
- * isWebsiteUrl validator
- */
-function IsWebsiteUrl(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isWebsiteUrl',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: util.isWebsiteUrl,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a valid website url.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid website URL (with or without protocol prefix).
+ */
+const websiteUrlType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isWebsiteUrl(val)) || ctx.mustBe('a valid website URL'));
 /**
- * isWebsiteUrlWithPrefix validator
- */
-function IsWebsiteUrlWithPrefix(validationOptions) {
-    return function (object, propertyName) {
-        classValidator.registerDecorator({
-            name: 'isWebsiteUrlWithPrefix',
-            target: object.constructor,
-            propertyName: propertyName,
-            options: validationOptions,
-            validator: {
-                validate: util.isWebsiteUrlWithPrefix,
-                defaultMessage: classValidator.buildMessage((eachPrefix, args) => eachPrefix + `$property value of "${args?.value}" is not a valid website url that starts with a http/https prefix.`, validationOptions)
-            }
-        });
-    };
-}
+ * ArkType schema for a valid website URL that starts with `http://` or `https://`.
+ */
+const websiteUrlWithPrefixType = arktype.type('string > 0').narrow((val, ctx) => (val != null && util.isWebsiteUrlWithPrefix(val)) || ctx.mustBe('a valid website URL starting with http:// or https://'));
 
 exports.ADDRESS_CITY_MAX_LENGTH = ADDRESS_CITY_MAX_LENGTH;
 exports.ADDRESS_COUNTRY_MAX_LENGTH = ADDRESS_COUNTRY_MAX_LENGTH;
@@ -1180,7 +1508,6 @@ exports.ADDRESS_STATE_CODE_MAX_LENGTH = ADDRESS_STATE_CODE_MAX_LENGTH;
 exports.ADDRESS_STATE_MAX_LENGTH = ADDRESS_STATE_MAX_LENGTH;
 exports.ADDRESS_ZIP_MAX_LENGTH = ADDRESS_ZIP_MAX_LENGTH;
 exports.AbstractModelPermissionService = AbstractModelPermissionService;
-exports.AbstractUnitedStatesAddressWithoutStateParams = AbstractUnitedStatesAddressWithoutStateParams;
 exports.CASHAPP_BASE_URL = CASHAPP_BASE_URL;
 exports.CASHAPP_USERNAME_PREFIX = CASHAPP_USERNAME_PREFIX;
 exports.CASHAPP_WEBSITE_LINK_TYPE = CASHAPP_WEBSITE_LINK_TYPE;
@@ -1197,14 +1524,6 @@ exports.GRANTED_UPDATE_ROLE_KEY = GRANTED_UPDATE_ROLE_KEY;
 exports.GrantedRoleMapReaderInstance = GrantedRoleMapReaderInstance;
 exports.INSTAGRAM_BASE_URL = INSTAGRAM_BASE_URL;
 exports.INSTAGRAM_WEBSITE_LINK_TYPE = INSTAGRAM_WEBSITE_LINK_TYPE;
-exports.IsE164PhoneNumber = IsE164PhoneNumber;
-exports.IsE164PhoneNumberWithExtension = IsE164PhoneNumberWithExtension;
-exports.IsE164PhoneNumberWithOptionalExtension = IsE164PhoneNumberWithOptionalExtension;
-exports.IsISO8601DayString = IsISO8601DayString;
-exports.IsMinuteOfDay = IsMinuteOfDay;
-exports.IsUniqueKeyed = IsUniqueKeyed;
-exports.IsWebsiteUrl = IsWebsiteUrl;
-exports.IsWebsiteUrlWithPrefix = IsWebsiteUrlWithPrefix;
 exports.NO_ACCESS_ROLE_KEY = NO_ACCESS_ROLE_KEY;
 exports.PAYPAL_BASE_URL = PAYPAL_BASE_URL;
 exports.PAYPAL_WEBSITE_LINK_TYPE = PAYPAL_WEBSITE_LINK_TYPE;
@@ -1220,13 +1539,7 @@ exports.TIKTOK_USERNAME_PREFIX = TIKTOK_USERNAME_PREFIX;
 exports.TIKTOK_WEBSITE_LINK_TYPE = TIKTOK_WEBSITE_LINK_TYPE;
 exports.TWITTER_BASE_URL = TWITTER_BASE_URL;
 exports.TWITTER_WEBSITE_LINK_TYPE = TWITTER_WEBSITE_LINK_TYPE;
-exports.TransformCommaSeparatedNumberValueToArray = TransformCommaSeparatedNumberValueToArray;
-exports.TransformCommaSeparatedStringValueToArray = TransformCommaSeparatedStringValueToArray;
-exports.TransformCommaSeparatedValueToArray = TransformCommaSeparatedValueToArray;
-exports.TransformStringValueToBoolean = TransformStringValueToBoolean;
 exports.UNKNOWN_WEBSITE_LINK_TYPE = UNKNOWN_WEBSITE_LINK_TYPE;
-exports.UnitedStatesAddressWithStateCodeParams = UnitedStatesAddressWithStateCodeParams;
-exports.UnitedStatesAddressWithStateStringParams = UnitedStatesAddressWithStateStringParams;
 exports.VENMO_BASE_URL = VENMO_BASE_URL;
 exports.VENMO_WEBSITE_LINK_ISOLATE_PROFILE_ID = VENMO_WEBSITE_LINK_ISOLATE_PROFILE_ID;
 exports.VENMO_WEBSITE_LINK_TYPE = VENMO_WEBSITE_LINK_TYPE;
@@ -1244,16 +1557,18 @@ exports.WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID = WEBSITE_LINK_ISOLATE_BASE_URL
 exports.WEBSITE_LINK_TYPE_MAX_LENGTH = WEBSITE_LINK_TYPE_MAX_LENGTH;
 exports.WEBSITE_LINK_TYPE_REGEX = WEBSITE_LINK_TYPE_REGEX;
 exports.WEBSITE_URL_WEBSITE_LINK_TYPE = WEBSITE_URL_WEBSITE_LINK_TYPE;
-exports.WebsiteFileLink = WebsiteFileLink;
-exports.WebsiteLink = WebsiteLink;
 exports.YOUTUBE_BASE_URL = YOUTUBE_BASE_URL;
 exports.YOUTUBE_WEBSITE_LINK_ISOLATE_PROFILE_ID = YOUTUBE_WEBSITE_LINK_ISOLATE_PROFILE_ID;
 exports.YOUTUBE_WEBSITE_LINK_TYPE = YOUTUBE_WEBSITE_LINK_TYPE;
 exports.basicSyncEntityCommonTypeSynchronizerInstanceFactory = basicSyncEntityCommonTypeSynchronizerInstanceFactory;
 exports.cashappProfileUrl = cashappProfileUrl;
 exports.cashappProfileUrlToWebsiteLink = cashappProfileUrlToWebsiteLink;
+exports.clearable = clearable;
 exports.contextGrantedModelRoles = contextGrantedModelRoles;
 exports.decodeWebsiteLinkEncodedDataToWebsiteFileLink = decodeWebsiteLinkEncodedDataToWebsiteFileLink;
+exports.e164PhoneNumberType = e164PhoneNumberType;
+exports.e164PhoneNumberWithExtensionType = e164PhoneNumberWithExtensionType;
+exports.e164PhoneNumberWithOptionalExtensionType = e164PhoneNumberWithOptionalExtensionType;
 exports.emailAddressToWebsiteLink = emailAddressToWebsiteLink;
 exports.encodeWebsiteFileLinkToWebsiteLinkEncodedData = encodeWebsiteFileLinkToWebsiteLinkEncodedData;
 exports.facebookProfileUrl = facebookProfileUrl;
@@ -1268,6 +1583,10 @@ exports.isFullAccessRoleMap = isFullAccessRoleMap;
 exports.isGrantedAdminLevelRole = isGrantedAdminLevelRole;
 exports.isNoAccessRoleMap = isNoAccessRoleMap;
 exports.isValidWebsiteLinkType = isValidWebsiteLinkType;
+exports.iso8601DayStringType = iso8601DayStringType;
+exports.minuteOfDayType = minuteOfDayType;
+exports.modelIdType = modelIdType;
+exports.modelKeyType = modelKeyType;
 exports.noAccessContextGrantedModelRoles = noAccessContextGrantedModelRoles;
 exports.noAccessRoleMap = noAccessRoleMap;
 exports.paypalProfileUrl = paypalProfileUrl;
@@ -1280,6 +1599,8 @@ exports.spotifyProfileUrlToWebsiteLink = spotifyProfileUrlToWebsiteLink;
 exports.syncEntityCommonTypeIdPairFactory = syncEntityCommonTypeIdPairFactory;
 exports.syncEntityFactory = syncEntityFactory;
 exports.syncEntitySynchronizer = syncEntitySynchronizer;
+exports.targetModelIdParamsType = targetModelIdParamsType;
+exports.targetModelParamsType = targetModelParamsType;
 exports.tiktokProfileUrl = tiktokProfileUrl;
 exports.tiktokProfileUrlToWebsiteLink = tiktokProfileUrlToWebsiteLink;
 exports.toTransformAndValidateFunctionResult = toTransformAndValidateFunctionResult;
@@ -1289,20 +1610,23 @@ exports.transformAndValidateObject = transformAndValidateObject;
 exports.transformAndValidateObjectFactory = transformAndValidateObjectFactory;
 exports.transformAndValidateObjectResult = transformAndValidateObjectResult;
 exports.transformAndValidateResultFactory = transformAndValidateResultFactory;
-exports.transformCommaSeparatedNumberValueToArray = transformCommaSeparatedNumberValueToArray;
-exports.transformCommaSeparatedStringValueToArray = transformCommaSeparatedStringValueToArray;
-exports.transformCommaSeparatedValueToArray = transformCommaSeparatedValueToArray;
-exports.transformStringToBoolean = transformStringToBoolean;
 exports.twitterProfileUrl = twitterProfileUrl;
 exports.twitterProfileUrlToWebsiteLink = twitterProfileUrlToWebsiteLink;
+exports.uniqueKeyedType = uniqueKeyedType;
+exports.unitedStatesAddressWithStateCodeType = unitedStatesAddressWithStateCodeType;
+exports.unitedStatesAddressWithStateStringType = unitedStatesAddressWithStateStringType;
 exports.usernameFromUsernameOrWebsiteWithBaseUrlUsername = usernameFromUsernameOrWebsiteWithBaseUrlUsername;
 exports.usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername = usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername;
 exports.usernameOrWebsiteUrlToWebsiteUrl = usernameOrWebsiteUrlToWebsiteUrl;
 exports.venmoProfileUrl = venmoProfileUrl;
 exports.venmoProfileUrlToWebsiteLink = venmoProfileUrlToWebsiteLink;
 exports.websiteFileLinkToWebsiteLink = websiteFileLinkToWebsiteLink;
+exports.websiteFileLinkType = websiteFileLinkType;
 exports.websiteLinkToWebsiteLinkFile = websiteLinkToWebsiteLinkFile;
+exports.websiteLinkType = websiteLinkType;
 exports.websiteUrlToWebsiteLink = websiteUrlToWebsiteLink;
+exports.websiteUrlType = websiteUrlType;
+exports.websiteUrlWithPrefixType = websiteUrlWithPrefixType;
 exports.youtubeProfileUrl = youtubeProfileUrl;
 exports.youtubeProfileUrlToWebsiteLink = youtubeProfileUrlToWebsiteLink;
 //# sourceMappingURL=index.cjs.js.map