@dereekb/model 13.0.6 → 13.1.0

package/src/lib/data/website/link.website.d.ts

@@ -1,104 +1,355 @@
 import { type E164PhoneNumber, type EmailAddress, type IsolateWebsitePathFunction, type ModelKey, type WebsiteUrl } from '@dereekb/util';
 import { type WebsiteLink, type WebsiteLinkType } from './link';
 /**
- * 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.
  *
- * Example:
- * - https://facebook.com/facebook
+ * 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
+ * ```typescript
+ * WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID('https://www.facebook.com/myuser');
+ * // returns 'myuser'
+ * ```
  */
 export declare const WEBSITE_LINK_ISOLATE_BASE_URL_PROFILE_ID: IsolateWebsitePathFunction;
+/**
+ * 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'
+ * ```
+ */
 export declare function usernameFromUsernameOrWebsiteWithBaseUrlUsername(input: ModelKey | WebsiteUrl, prefix?: string): string;
+/**
+ * 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
+ */
 export declare function usernameFromUsernameOrWebsiteWithOneOffBaseUrlUsername(input: ModelKey | WebsiteUrl, isolateFn: IsolateWebsitePathFunction): string;
+/**
+ * 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
+ */
 export declare function usernameOrWebsiteUrlToWebsiteUrl(input: string): WebsiteUrl;
+/**
+ * {@link WebsiteLinkType} code for generic website URLs.
+ */
 export declare 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'
+ * ```
+ */
 export declare function websiteUrlToWebsiteLink(input: WebsiteUrl): WebsiteLink;
+/**
+ * {@link WebsiteLinkType} code for email addresses.
+ */
 export declare 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
+ */
 export declare function emailAddressToWebsiteLink(input: EmailAddress): WebsiteLink;
+/**
+ * {@link WebsiteLinkType} code for phone numbers.
+ */
 export declare 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
+ */
 export declare function phoneNumberToWebsiteLink(input: E164PhoneNumber): WebsiteLink;
+/** Base URL for Facebook profiles. */
 export declare const FACEBOOK_BASE_URL = "https://www.facebook.com";
+/** {@link WebsiteLinkType} code for Facebook. */
 export declare const FACEBOOK_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type FacebookBaseUrl = typeof FACEBOOK_BASE_URL;
 export type FacebookProfileUrl<P extends FacebookProfileId> = `${FacebookBaseUrl}/${P}`;
 export type FacebookProfileId = string;
 export type FacebookWebsiteLinkType = typeof FACEBOOK_WEBSITE_LINK_TYPE;
+/**
+ * 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' }
+ * ```
+ */
 export declare function facebookProfileUrlToWebsiteLink(input: FacebookProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Facebook profile URL from a profile ID.
+ *
+ * @param profileId - the Facebook profile ID or username
+ * @returns the full profile URL
+ */
 export declare function facebookProfileUrl<P extends FacebookProfileId>(profileId: P): FacebookProfileUrl<P>;
+/** Base URL for Instagram profiles. */
 export declare const INSTAGRAM_BASE_URL = "https://www.instagram.com";
+/** {@link WebsiteLinkType} code for Instagram. */
 export declare const INSTAGRAM_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type InstagramBaseUrl = typeof INSTAGRAM_BASE_URL;
 export type InstagramProfileUrl<P extends InstagramProfileId> = `${InstagramBaseUrl}/${P}`;
 export type InstagramProfileId = string;
 export type InstagramWebsiteLinkType = typeof INSTAGRAM_WEBSITE_LINK_TYPE;
+/**
+ * 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
+ */
 export declare function instagramProfileUrlToWebsiteLink(input: InstagramProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Instagram profile URL from a profile ID.
+ *
+ * @param profileId - the Instagram username
+ * @returns the full profile URL
+ */
 export declare function instagramProfileUrl<P extends InstagramProfileId>(profileId: P): InstagramProfileUrl<P>;
+/** Base URL for Twitter profiles. */
 export declare const TWITTER_BASE_URL = "https://www.twitter.com";
+/** {@link WebsiteLinkType} code for Twitter. */
 export declare const TWITTER_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type TwitterBaseUrl = typeof TWITTER_BASE_URL;
 export type TwitterProfileUrl<P extends TwitterProfileId> = `${TwitterBaseUrl}/${P}`;
 export type TwitterProfileId = string;
 export type TwitterWebsiteLinkType = typeof TWITTER_WEBSITE_LINK_TYPE;
+/**
+ * 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
+ */
 export declare function twitterProfileUrlToWebsiteLink(input: TwitterProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Twitter profile URL from a profile ID.
+ *
+ * @param profileId - the Twitter username
+ * @returns the full profile URL
+ */
 export declare function twitterProfileUrl<P extends TwitterProfileId>(profileId: P): TwitterProfileUrl<P>;
+/** Base URL for TikTok profiles. */
 export declare const TIKTOK_BASE_URL = "https://tiktok.com";
+/** TikTok usernames are prefixed with "@" in URLs and stored data. */
 export declare const TIKTOK_USERNAME_PREFIX = "@";
+/** {@link WebsiteLinkType} code for TikTok. */
 export declare const TIKTOK_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type TikTokBaseUrl = typeof TIKTOK_BASE_URL;
 export type TikTokProfileUrl<P extends TikTokProfileId> = `${TikTokBaseUrl}/@${P}`;
 export type TikTokProfileId = string;
 export type TikTokWebsiteLinkType = typeof TIKTOK_WEBSITE_LINK_TYPE;
+/**
+ * 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
+ */
 export declare function tiktokProfileUrlToWebsiteLink(input: TikTokProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full TikTok profile URL from a profile ID.
+ *
+ * @param profileId - the TikTok username (without "@" prefix)
+ * @returns the full profile URL with "@" prefix
+ */
 export declare function tiktokProfileUrl<P extends TikTokProfileId>(profileId: P): TikTokProfileUrl<P>;
+/** Base URL for Snapchat profiles. */
 export declare const SNAPCHAT_BASE_URL = "https://snapchat.com";
+/** {@link WebsiteLinkType} code for Snapchat. */
 export declare const SNAPCHAT_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type SnapchatBaseUrl = typeof SNAPCHAT_BASE_URL;
 export type SnapchatProfileUrl<P extends SnapchatProfileId> = `${SnapchatBaseUrl}/add/${P}`;
 export type SnapchatProfileId = string;
 export type SnapchatWebsiteLinkType = typeof SNAPCHAT_WEBSITE_LINK_TYPE;
+/**
+ * Isolates a Snapchat username from a URL, ignoring the `/add/` base path segment.
+ */
 export declare const SNAPCHAT_WEBSITE_LINK_ISOLATE_PROFILE_ID: IsolateWebsitePathFunction;
+/**
+ * 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
+ */
 export declare function snapchatProfileUrlToWebsiteLink(input: SnapchatProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Snapchat profile URL from a profile ID.
+ *
+ * @param profileId - the Snapchat username
+ * @returns the full profile URL with `/add/` path
+ */
 export declare function snapchatProfileUrl<P extends SnapchatProfileId>(profileId: P): SnapchatProfileUrl<P>;
+/** Base URL for YouTube channels. */
 export declare const YOUTUBE_BASE_URL = "https://youtube.com";
+/** {@link WebsiteLinkType} code for YouTube. */
 export declare const YOUTUBE_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type YouTubeBaseUrl = typeof YOUTUBE_BASE_URL;
 export type YouTubeProfileUrl<P extends YouTubeProfileId> = `${YouTubeBaseUrl}/c/${P}`;
 export type YouTubeProfileId = string;
 export type YouTubeWebsiteLinkType = typeof YOUTUBE_WEBSITE_LINK_TYPE;
+/**
+ * Isolates a YouTube channel name from a URL, ignoring the `/c/` base path segment.
+ */
 export declare const YOUTUBE_WEBSITE_LINK_ISOLATE_PROFILE_ID: IsolateWebsitePathFunction;
+/**
+ * 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
+ */
 export declare function youtubeProfileUrlToWebsiteLink(input: YouTubeProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full YouTube channel URL from a profile ID.
+ *
+ * @param profileId - the YouTube channel name
+ * @returns the full channel URL with `/c/` path
+ */
 export declare function youtubeProfileUrl<P extends YouTubeProfileId>(profileId: P): YouTubeProfileUrl<P>;
+/** Base URL for PayPal.me profiles. */
 export declare const PAYPAL_BASE_URL = "https://paypal.me";
+/** {@link WebsiteLinkType} code for PayPal. */
 export declare const PAYPAL_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type PayPalBaseUrl = typeof PAYPAL_BASE_URL;
 export type PayPalProfileUrl<P extends PayPalProfileId> = `${PayPalBaseUrl}/${P}`;
 export type PayPalProfileId = string;
 export type PayPalWebsiteLinkType = typeof PAYPAL_WEBSITE_LINK_TYPE;
+/**
+ * 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
+ */
 export declare function paypalProfileUrlToWebsiteLink(input: PayPalProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full PayPal.me profile URL from a profile ID.
+ *
+ * @param profileId - the PayPal username
+ * @returns the full PayPal.me URL
+ */
 export declare function paypalProfileUrl<P extends PayPalProfileId>(profileId: P): PayPalProfileUrl<P>;
+/** Base URL for Cash App profiles. */
 export declare const CASHAPP_BASE_URL = "https://cash.app";
+/** Cash App usernames are prefixed with "$" (cashtag). */
 export declare const CASHAPP_USERNAME_PREFIX = "$";
+/** {@link WebsiteLinkType} code for Cash App. */
 export declare const CASHAPP_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type CashappBaseUrl = typeof CASHAPP_BASE_URL;
 export type CashappProfileUrl<P extends CashappProfileId> = `${CashappBaseUrl}/$${P}`;
 export type CashappProfileId = string;
 export type CashappWebsiteLinkType = typeof CASHAPP_WEBSITE_LINK_TYPE;
+/**
+ * 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
+ */
 export declare function cashappProfileUrlToWebsiteLink(input: CashappProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * 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
+ */
 export declare function cashappProfileUrl<P extends CashappProfileId>(profileId: P): CashappProfileUrl<P>;
+/** Base URL for Venmo profiles. */
 export declare const VENMO_BASE_URL = "https://account.venmo.com";
+/** {@link WebsiteLinkType} code for Venmo. */
 export declare const VENMO_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type VenmoBaseUrl = typeof VENMO_BASE_URL;
 export type VenmoProfileUrl<P extends VenmoProfileId> = `${VenmoBaseUrl}/u/${P}`;
 export type VenmoProfileId = string;
 export type VenmoWebsiteLinkType = typeof VENMO_WEBSITE_LINK_TYPE;
+/**
+ * Isolates a Venmo username from a URL, ignoring the `/u/` base path segment.
+ */
 export declare const VENMO_WEBSITE_LINK_ISOLATE_PROFILE_ID: IsolateWebsitePathFunction;
+/**
+ * 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
+ */
 export declare function venmoProfileUrlToWebsiteLink(input: VenmoProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Venmo profile URL from a profile ID.
+ *
+ * @param profileId - the Venmo username
+ * @returns the full profile URL with `/u/` path
+ */
 export declare function venmoProfileUrl<P extends VenmoProfileId>(profileId: P): VenmoProfileUrl<P>;
+/** Base URL for Spotify profiles. */
 export declare const SPOTIFY_BASE_URL = "https://open.spotify.com/";
+/** {@link WebsiteLinkType} code for Spotify. */
 export declare const SPOTIFY_WEBSITE_LINK_TYPE: WebsiteLinkType;
 export type SpotifyBaseUrl = typeof SPOTIFY_BASE_URL;
 export type SpotifyProfileUrl<P extends SpotifyProfileId> = `${SpotifyBaseUrl}/user/${P}`;
 export type SpotifyProfileId = string;
 export type SpotifyWebsiteLinkType = typeof SPOTIFY_WEBSITE_LINK_TYPE;
+/**
+ * Isolates a Spotify username from a URL, ignoring the `/user/` base path segment.
+ */
 export declare const SPOTIFY_WEBSITE_LINK_ISOLATE_PROFILE_ID: IsolateWebsitePathFunction;
+/**
+ * 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
+ */
 export declare function spotifyProfileUrlToWebsiteLink(input: SpotifyProfileId | WebsiteUrl): WebsiteLink;
+/**
+ * Constructs a full Spotify profile URL from a profile ID.
+ *
+ * @param profileId - the Spotify username
+ * @returns the full profile URL with `/user/` path
+ */
 export declare function spotifyProfileUrl<P extends SpotifyProfileId>(profileId: P): SpotifyProfileUrl<P>;

package/src/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './data';
 export * from './service';
 export * from './transform';
+export * from './type';
 export * from './validator';

package/src/lib/service/permission/permission.d.ts

@@ -1,13 +1,49 @@
 import { type Maybe } from '@dereekb/util';
 import { type GrantedRoleMap } from './role';
 /**
- * Object that contains granted roles, a model, and the context the roles were granted in.
+ * Container that associates a model's data, the context in which roles were evaluated, and the resulting granted role map.
+ *
+ * Returned by permission services after evaluating what roles a given context has for a specific model.
  */
 export interface ContextGrantedModelRoles<O, C = unknown, R extends string = string> {
     readonly data: Maybe<O>;
     readonly context: C;
     readonly roleMap: GrantedRoleMap<R>;
 }
+/**
+ * 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
+ * ```
+ */
 export declare function noAccessContextGrantedModelRoles<O, C = unknown, R extends string = string>(context: C, data?: Maybe<O>): ContextGrantedModelRoles<O, C, R>;
+/**
+ * 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
+ * ```
+ */
 export declare function fullAccessGrantedModelRoles<O, C = unknown, R extends string = string>(context: C, data?: Maybe<O>): ContextGrantedModelRoles<O, C, R>;
+/**
+ * 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
+ */
 export declare function contextGrantedModelRoles<O, C = unknown, R extends string = string>(context: C, data: Maybe<O>, roles: GrantedRoleMap<R>): ContextGrantedModelRoles<O, C, R>;

package/src/lib/service/permission/role.d.ts

@@ -19,10 +19,17 @@ export declare const GRANTED_OWNER_ROLE_KEY = "owner";
 export type GrantedAdminRole = typeof GRANTED_ADMIN_ROLE_KEY;
 export declare 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
+ * ```
  */
 export declare function isGrantedAdminLevelRole(role: GrantedRole): boolean;
 /**
@@ -51,12 +58,46 @@ export type NoAccessGrantedRole = typeof NO_ACCESS_ROLE_KEY;
 export type NoAccessRoleMap = {
     [NO_ACCESS_ROLE_KEY]: true;
 };
+/**
+ * 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
+ * ```
+ */
 export declare function noAccessRoleMap<R extends string = string>(): GrantedRoleMap<R>;
+/**
+ * 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
+ */
 export declare function isNoAccessRoleMap<R extends string = string>(input: GrantedRoleMap<R> | NoAccessRoleMap): input is NoAccessRoleMap;
 export type FullAccessRoleMap = {
     [FULL_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
+ * ```
+ */
 export declare function fullAccessRoleMap<R extends string = string>(): GrantedRoleMap<R>;
+/**
+ * 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
+ */
 export declare function isFullAccessRoleMap<R extends string = string>(input: GrantedRoleMap<R> | FullAccessRoleMap): input is FullAccessRoleMap;
 export type GrantedRoleMap<R extends GrantedRole = string> = NoAccessRoleMap | FullAccessRoleMap | GrantedRoleKeysMap<R>;
 export type GrantedRoleKeysMap<R extends GrantedRole = string> = {
@@ -102,10 +143,24 @@ export interface GrantedRoleMapReader<R extends GrantedRole = GrantedRole> {
     containsRoles(setIncludes: SetIncludesMode, roles: ArrayOrValue<R> | IterableOrValue<R>): boolean;
 }
 /**
- * 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
+ * ```
  */
 export declare function grantedRoleMapReader<R extends GrantedRole = string>(map: GrantedRoleMap<R>): GrantedRoleMapReader<R>;
 export declare class GrantedRoleMapReaderInstance<R extends GrantedRole = string> implements GrantedRoleMapReader<R> {
@@ -120,9 +175,16 @@ export declare class GrantedRoleMapReaderInstance<R extends GrantedRole = string
     containsEachRole(roles: ArrayOrValue<R>): boolean;
 }
 /**
- * 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 - 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
  *
- * @param roles
- * @returns
+ * @example
+ * ```typescript
+ * const map = grantedRoleKeysMapFromArray(['read', 'update']);
+ * // { read: true, update: true }
+ * ```
  */
 export declare function grantedRoleKeysMapFromArray<R extends GrantedRole = string>(roles: R[], value?: boolean): GrantedRoleKeysMap<R>;

package/src/lib/service/sync/sync.entity.d.ts

@@ -23,6 +23,22 @@ export interface SyncEntityCommonTypeIdPair {
 }
 export type SyncEntityCommonTypeIdPairFactoryInput = SyncEntityCommonTypeIdPair | SyncEntityCommonId;
 export type SyncEntityCommonTypeIdPairFactory = (input: SyncEntityCommonTypeIdPairFactoryInput) => SyncEntityCommonTypeIdPair;
+/**
+ * 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
+ * ```
+ */
 export declare function syncEntityCommonTypeIdPairFactory(commonType: SyncEntityCommonType): SyncEntityCommonTypeIdPairFactory;
 /**
  * Represents a single entity that can be synchronized between different servers.
@@ -55,9 +71,22 @@ export interface SyncEntityFactoryConfig {
  */
 export type SyncEntityFactory = FactoryWithRequiredInput<SyncEntity, SyncEntityCommonTypeIdPair>;
 /**
- * Creates a SyncEntityFactory.
+ * Creates a {@link SyncEntityFactory} that produces {@link SyncEntity} instances from a common type/id pair.
+ *
+ * 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' }
+ * });
  *
- * @param config
- * @returns
+ * const entity = factory({ commonType: 'user', commonId: 'abc123' });
+ * // entity.id === 'abc123', entity.sourceInfo.id === 'api'
+ * ```
  */
 export declare function syncEntityFactory(config: SyncEntityFactoryConfig): SyncEntityFactory;

package/src/lib/service/sync/sync.entity.synchronizer.basic.d.ts

@@ -114,4 +114,19 @@ export interface BasicSyncEntityCommonTypeSynchronizerConfig {
      */
     readonly entitySourceContextLoader: BasicSyncEntityCommonTypeSynchronizerEntitySourceContextLoader;
 }
+/**
+ * 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
+ */
 export declare function basicSyncEntityCommonTypeSynchronizerInstanceFactory(config: BasicSyncEntityCommonTypeSynchronizerConfig): BasicSyncEntityCommonTypeSynchronizer;

package/src/lib/service/sync/sync.entity.synchronizer.d.ts

@@ -50,6 +50,26 @@ export interface SyncEntitySynchronizer {
 export interface SyncEntitySynchronizerConfig {
     readonly commonTypeSynchronizers: SyncEntityCommonTypeSynchronizer[];
 }
+/**
+ * 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();
+ * ```
+ */
 export declare function syncEntitySynchronizer(config: SyncEntitySynchronizerConfig): SyncEntitySynchronizer;
 export type SyncEntityCommonTypeSynchronizerInstanceInput = SyncEntityCommonTypeIdPairFactoryInput;
 export type SyncEntityCommonTypeSynchronizerInstanceFunction = (input: SyncEntityCommonTypeSynchronizerInstanceInput) => Promise<SyncEntityCommonTypeSynchronizerInstance>;

package/src/lib/transform/index.d.ts

@@ -1,5 +1,3 @@
-export * from './type';
-export * from './type.annotation';
 export * from './transform';
 export * from './transform.function';
 export * from './transform.result';