@vltpkg/types 0.0.0-3 → 0.0.0-31

package/dist/esm/index.js

@@ -1,5 +1,428 @@
 import { error } from '@vltpkg/error-cause';
-const integrityRE = /^sha512-[a-zA-Z0-9/+]{86}==$/;
+import { Version } from '@vltpkg/semver';
+/**
+ * Normalize a single funding entry to a consistent format.
+ */
+const normalizeFundingEntry = (item) => {
+    const getTypeFromUrl = (url) => {
+        try {
+            const { hostname } = new URL(url);
+            const domain = hostname.startsWith('www.') ? hostname.slice(4) : hostname;
+            if (domain === 'github.com')
+                return 'github';
+            if (domain === 'patreon.com')
+                return 'patreon';
+            if (domain === 'opencollective.com')
+                return 'opencollective';
+            return 'individual';
+        }
+        catch {
+            return 'invalid';
+        }
+    };
+    const validateType = (url, type) => {
+        const urlType = getTypeFromUrl(url);
+        if (!type ||
+            ['github', 'patreon', 'opencollective'].includes(urlType))
+            return urlType;
+        if (urlType === 'invalid')
+            return undefined;
+        return type;
+    };
+    if (typeof item === 'string') {
+        return { url: item, type: getTypeFromUrl(item) };
+    }
+    if (isObject(item) &&
+        'url' in item &&
+        typeof item.url === 'string') {
+        // If the item is already normalized, return it directly
+        if (isNormalizedFundingEntry(item)) {
+            return item;
+        }
+        const obj = item;
+        const url = obj.url;
+        const validatedType = validateType(url, obj.type);
+        const result = { ...obj, url };
+        if (validatedType) {
+            result.type = validatedType;
+        }
+        else {
+            delete result.type;
+        }
+        return result;
+    }
+    return { url: '', type: 'individual' };
+};
+/**
+ * Normalize funding information to a consistent format.
+ */
+export const normalizeFunding = (funding) => {
+    if (!funding)
+        return;
+    const fundingArray = Array.isArray(funding) ? funding : [funding];
+    const sources = fundingArray.map(normalizeFundingEntry);
+    return sources.length > 0 ? sources : undefined;
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedFundingEntry}.
+ */
+export const isNormalizedFundingEntry = (o) => {
+    return (isObject(o) &&
+        'url' in o &&
+        typeof o.url === 'string' &&
+        !!o.url &&
+        'type' in o &&
+        typeof o.type === 'string' &&
+        ['github', 'patreon', 'opencollective', 'individual'].includes(o.type));
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedFunding}.
+ */
+export const isNormalizedFunding = (o) => {
+    return (Array.isArray(o) &&
+        o.length > 0 &&
+        o.every(isNormalizedFundingEntry));
+};
+/**
+ * Given a version Normalize the version field in a manifest.
+ */
+export const fixManifestVersion = (manifest) => {
+    if (!Object.hasOwn(manifest, 'version')) {
+        return manifest;
+    }
+    if (!manifest.version) {
+        throw error('version is empty', {
+            manifest,
+        });
+    }
+    const version = Version.parse(manifest.version);
+    manifest.version = version.toString();
+    return manifest;
+};
+const kWriteAccess = Symbol.for('writeAccess');
+const kIsPublisher = Symbol.for('isPublisher');
+/**
+ * Parse a string or object into a normalized contributor.
+ */
+export const parsePerson = (person, writeAccess, isPublisher) => {
+    if (!person)
+        return;
+    if (isObject(person)) {
+        // this is an already parsed object person, just return its value
+        if (isNormalizedContributorEntry(person)) {
+            return person;
+        }
+        const name = typeof person.name === 'string' ? person.name : undefined;
+        const email = typeof person.email === 'string' ? person.email
+            : typeof person.mail === 'string' ? person.mail
+                : undefined;
+        if (!name && !email)
+            return undefined;
+        return {
+            name,
+            email,
+            [kWriteAccess]: writeAccess ?? false,
+            [kIsPublisher]: isPublisher ?? false,
+        };
+    }
+    else if (typeof person === 'string') {
+        const NAME_PATTERN = /^([^(<]+)/;
+        const EMAIL_PATTERN = /<([^<>]+)>/;
+        const name = NAME_PATTERN.exec(person)?.[0].trim() || '';
+        const email = EMAIL_PATTERN.exec(person)?.[1] || '';
+        if (!name && !email)
+            return undefined;
+        return {
+            name: name || undefined,
+            email: email || undefined,
+            [kWriteAccess]: writeAccess ?? false,
+            [kIsPublisher]: isPublisher ?? false,
+        };
+    }
+    return;
+};
+/**
+ * Type guard to check if a value is a normalized contributor entry.
+ */
+export const isNormalizedContributorEntry = (o) => {
+    return (isObject(o) &&
+        typeof o.name === 'string' &&
+        !!o.name &&
+        typeof o.email === 'string' &&
+        !!o.email &&
+        (isBoolean(o[kWriteAccess]) ||
+            isBoolean(o.writeAccess)) &&
+        (isBoolean(o[kIsPublisher]) ||
+            isBoolean(o.isPublisher)));
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedContributors}.
+ */
+export const isNormalizedContributors = (o) => {
+    return (Array.isArray(o) &&
+        o.length > 0 &&
+        o.every(isNormalizedContributorEntry));
+};
+/**
+ * Normalize contributors and maintainers from various formats
+ */
+export const normalizeContributors = (contributors, maintainers) => {
+    if (!contributors && !maintainers)
+        return;
+    const result = [];
+    // Parse regular contributors (if any)
+    if (contributors) {
+        const contributorsArray = Array.isArray(contributors) ? contributors : [contributors];
+        const normalizedArray = contributorsArray.every(isNormalizedContributorEntry);
+        const noMaintainers = !maintainers ||
+            (Array.isArray(maintainers) && maintainers.length === 0);
+        // If all contributors are already normalized, and there are
+        // no maintainers, return the contributors directly
+        if (normalizedArray) {
+            if (noMaintainers) {
+                return contributorsArray.length > 0 ?
+                    contributorsArray
+                    : undefined;
+            }
+            else {
+                result.push(...contributorsArray);
+            }
+        }
+        // Parse each contributor and filter out undefined values
+        const parsedContributors = contributorsArray
+            .map(person => parsePerson(person))
+            .filter((c) => c !== undefined);
+        result.push(...parsedContributors);
+    }
+    // Parse maintainers with special flags
+    if (maintainers) {
+        const maintainersArray = Array.isArray(maintainers) ? maintainers : [maintainers];
+        const parsedMaintainers = maintainersArray
+            .map(person => parsePerson(person, true, true))
+            .filter((c) => c !== undefined);
+        result.push(...parsedMaintainers);
+    }
+    return result.length > 0 ? result : undefined;
+};
+/**
+ * Helper function to normalize a single {@link Bugs} entry.
+ */
+const normalizeSingleBug = (bug) => {
+    const res = [];
+    if (typeof bug === 'string') {
+        // Try to parse as URL first - if it succeeds, treat as link
+        try {
+            new URL(bug);
+            res.push({ type: 'link', url: bug });
+        }
+        catch {
+            // TODO: need a more robust email validation, likely
+            // to be replaced with valibot / zod
+            // If URL parsing fails, check if it's a valid email
+            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+            if (emailRegex.test(bug)) {
+                res.push({ type: 'email', email: bug });
+            }
+            else {
+                // Default to link for plain strings like 'example.com'
+                res.push({ type: 'link', url: bug });
+            }
+        }
+    }
+    else if (isObject(bug)) {
+        if (isNormalizedBugsEntry(bug)) {
+            res.push(bug);
+        }
+        const obj = bug;
+        if (obj.url) {
+            res.push({ type: 'link', url: obj.url });
+        }
+        if (obj.email) {
+            res.push({ type: 'email', email: obj.email });
+        }
+    }
+    return res.length > 0 ? res : [];
+};
+/**
+ * Normalize bugs information to a {@link NormalizedBugs} consistent format.
+ */
+export const normalizeBugs = (bugs) => {
+    if (!bugs)
+        return;
+    const result = [];
+    // Handle array of bugs entries
+    if (Array.isArray(bugs)) {
+        for (const bug of bugs) {
+            result.push(...normalizeSingleBug(bug));
+        }
+    }
+    else {
+        // Handle single bugs entry
+        result.push(...normalizeSingleBug(bugs));
+    }
+    return result.length > 0 ? result : undefined;
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedBugsEntry}.
+ */
+export const isNormalizedBugsEntry = (o) => {
+    return (isObject(o) &&
+        'type' in o &&
+        ((o.type === 'email' &&
+            typeof o.email === 'string' &&
+            !!o.email) ||
+            (o.type === 'link' && typeof o.url === 'string' && !!o.url)));
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedBugs}.
+ */
+export const isNormalizedBugs = (o) => {
+    return (Array.isArray(o) && o.length > 0 && o.every(isNormalizedBugsEntry));
+};
+/**
+ * Normalize keywords information to a {@link NormalizedKeywords} consistent format.
+ */
+export const normalizeKeywords = (keywords) => {
+    if (!keywords)
+        return;
+    let keywordArray = [];
+    if (typeof keywords === 'string') {
+        // Handle comma-separated string values
+        keywordArray = keywords
+            .split(',')
+            .map(keyword => keyword.trim())
+            .filter(keyword => keyword.length > 0);
+    }
+    else if (Array.isArray(keywords)) {
+        // If all keywords are already normalized, return them directly
+        if (isNormalizedKeywords(keywords)) {
+            return keywords;
+        }
+        // Handle array of strings, filter out empty/invalid entries
+        keywordArray = keywords
+            .filter((keyword) => typeof keyword === 'string')
+            .map(keyword => keyword.trim())
+            .filter(keyword => keyword.length > 0);
+    }
+    else {
+        // Invalid format
+        return;
+    }
+    return keywordArray.length > 0 ? keywordArray : undefined;
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedKeywords}.
+ */
+export const isNormalizedKeywords = (o) => {
+    return (Array.isArray(o) &&
+        o.length > 0 &&
+        o.every(keyword => typeof keyword === 'string' &&
+            !!keyword &&
+            !keyword.startsWith(' ') &&
+            !keyword.endsWith(' ')));
+};
+/**
+ * Normalize engines information to a {@link NormalizedEngines} consistent format.
+ */
+export const normalizeEngines = (engines) => {
+    if (!engines)
+        return;
+    if (isNormalizedEngines(engines)) {
+        // Return undefined if empty object
+        return Object.keys(engines).length === 0 ? undefined : engines;
+    }
+    // Invalid format
+    return;
+};
+/**
+ * Normalize OS information to a {@link NormalizedOs} consistent format.
+ */
+export const normalizeOs = (os) => {
+    if (!os)
+        return;
+    let osArray = [];
+    if (typeof os === 'string') {
+        // Handle single OS string
+        osArray = [os.trim()].filter(item => item.length > 0);
+    }
+    else if (Array.isArray(os)) {
+        // If all OS entries are already normalized, return them directly
+        if (isNormalizedOs(os)) {
+            return os;
+        }
+        // Handle array of strings, filter out empty/invalid entries
+        osArray = os
+            .filter((item) => typeof item === 'string')
+            .map(item => item.trim())
+            .filter(item => item.length > 0);
+    }
+    else {
+        // Invalid format
+        return;
+    }
+    return osArray.length > 0 ? osArray : undefined;
+};
+/**
+ * Normalize CPU information to a {@link NormalizedCpu} consistent format.
+ */
+export const normalizeCpu = (cpu) => {
+    if (!cpu)
+        return;
+    let cpuArray = [];
+    if (typeof cpu === 'string') {
+        // Handle single CPU string
+        cpuArray = [cpu.trim()].filter(item => item.length > 0);
+    }
+    else if (Array.isArray(cpu)) {
+        // If all CPU entries are already normalized, return them directly
+        if (isNormalizedCpu(cpu)) {
+            return cpu;
+        }
+        // Handle array of strings, filter out empty/invalid entries
+        cpuArray = cpu
+            .filter((item) => typeof item === 'string')
+            .map(item => item.trim())
+            .filter(item => item.length > 0);
+    }
+    else {
+        // Invalid format
+        return;
+    }
+    return cpuArray.length > 0 ? cpuArray : undefined;
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedEngines}.
+ */
+export const isNormalizedEngines = (o) => {
+    return isRecordStringString(o);
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedOs}.
+ */
+export const isNormalizedOs = (o) => {
+    return (Array.isArray(o) &&
+        o.length > 0 &&
+        o.every(item => typeof item === 'string' &&
+            !!item &&
+            !item.startsWith(' ') &&
+            !item.endsWith(' ')));
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedCpu}.
+ */
+export const isNormalizedCpu = (o) => {
+    return (Array.isArray(o) &&
+        o.length > 0 &&
+        o.every(item => typeof item === 'string' &&
+            !!item &&
+            !item.startsWith(' ') &&
+            !item.endsWith(' ')));
+};
+/**
+ * A type guard to check if a value is a boolean.
+ */
+export const isBoolean = (value) => typeof value === 'boolean';
+export const integrityRE = /^sha512-[a-zA-Z0-9/+]{86}==$/;
 export const isIntegrity = (i) => typeof i === 'string' && integrityRE.test(i);
 export const asIntegrity = (i) => {
     if (!isIntegrity(i)) {
@@ -13,7 +436,7 @@ export const asIntegrity = (i) => {
 export const assertIntegrity = i => {
     asIntegrity(i);
 };
-const keyIDRE = /^SHA256:[a-zA-Z0-9/+]{43}$/;
+export const keyIDRE = /^SHA256:[a-zA-Z0-9/+]{43}$/;
 export const isKeyID = (k) => typeof k === 'string' && keyIDRE.test(k);
 export const asKeyID = (k) => {
     if (!isKeyID(k)) {
@@ -27,19 +450,52 @@ export const asKeyID = (k) => {
 export const assertKeyID = k => {
     asKeyID(k);
 };
-const isObj = (o) => !!o && typeof o === 'object';
-const maybeRecordStringString = (o) => o === undefined || isRecordStringString(o);
-const isRecordStringString = (o) => isRecordStringT(o, s => typeof s === 'string');
-const isRecordStringT = (o, check) => isObj(o) &&
+/**
+ * Convert an unknown value to an error.
+ */
+export const asError = (er, fallbackMessage = 'Unknown error') => er instanceof Error ? er : new Error(String(er) || fallbackMessage);
+/**
+ * Check if a value is an error.
+ */
+export const isError = (er) => er instanceof Error;
+/**
+ * Check if an error has a cause property.
+ */
+export const isErrorWithCause = (er) => isError(er) && 'cause' in er;
+/**
+ * Check if an unknown value is a plain object.
+ */
+export const isObject = (v) => !!v &&
+    typeof v === 'object' &&
+    (v.constructor === Object ||
+        v.constructor === undefined);
+export const maybeRecordStringString = (o) => o === undefined || isRecordStringString(o);
+export const isRecordStringString = (o) => isRecordStringT(o, s => typeof s === 'string');
+export const assertRecordStringString = (o) => assertRecordStringT(o, s => typeof s === 'string', 'Record<string, string>');
+export const isRecordStringT = (o, check) => isObject(o) &&
     Object.entries(o).every(([k, v]) => typeof k === 'string' && check(v));
-const isRecordStringManifest = (o) => isRecordStringT(o, v => isManifest(v));
-const maybePeerDependenciesMetaSet = (o) => o === undefined ||
+export const assertRecordStringT = (o, check, 
+/** a type description, like 'Record<string, Record<string, string>>' */
+wanted) => {
+    if (!isRecordStringT(o, check)) {
+        throw error('Invalid record', {
+            found: o,
+            wanted,
+        });
+    }
+};
+export const isRecordStringManifest = (o) => isRecordStringT(o, v => isManifest(v));
+export const maybePeerDependenciesMetaSet = (o) => o === undefined ||
     isRecordStringT(o, v => isPeerDependenciesMetaValue(v));
-const maybeBoolean = (o) => o === undefined || typeof o === 'boolean';
-const isPeerDependenciesMetaValue = (o) => isObj(o) && maybeBoolean(o.optional);
-const maybeString = (a) => a === undefined || typeof a === 'string';
-const maybeDist = (a) => a === undefined || (isObj(a) && maybeString(a.tarball));
-export const isManifest = (m) => isObj(m) &&
+export const maybeBoolean = (o) => o === undefined || typeof o === 'boolean';
+export const isPeerDependenciesMetaValue = (o) => isObject(o) && maybeBoolean(o.optional);
+export const maybeString = (a) => a === undefined || typeof a === 'string';
+export const maybeDist = (a) => a === undefined || (isObject(a) && maybeString(a.tarball));
+/**
+ * Is a given unknown value a valid {@link Manifest} object?
+ * Returns `true` if so.
+ */
+export const isManifest = (m) => isObject(m) &&
     !Array.isArray(m) &&
     maybeString(m.name) &&
     maybeString(m.version) &&
@@ -50,19 +506,172 @@ export const isManifest = (m) => isObj(m) &&
     maybeRecordStringString(m.acceptDependencies) &&
     maybePeerDependenciesMetaSet(m.peerDependenciesMeta) &&
     maybeDist(m.dist);
+/**
+ * A specific {@link Manifest} that is retrieved uniquely from reading
+ * registry packument and manifest endpoints, it has `dist`, `name` and
+ * `version` fields defined.
+ */
 export const isManifestRegistry = (m) => isManifest(m) && !!m.dist && !!m.name && !!m.version;
+/**
+ * Given an unknown value, convert it to a {@link Manifest}.
+ */
 export const asManifest = (m, from) => {
     if (!isManifest(m)) {
         throw error('invalid manifest', { found: m }, from ?? asManifest);
     }
     return m;
 };
+/**
+ * Given a {@link Manifest} returns a {@link NormalizedManifest} that
+ * contains normalized author, bugs, funding, contributors, keywords and
+ * version fields.
+ */
+export const normalizeManifest = (manifest) => {
+    manifest = fixManifestVersion(manifest);
+    const normalizedAuthor = parsePerson(manifest.author);
+    const normalizedFunding = normalizeFunding(manifest.funding);
+    const normalizedContributors = normalizeContributors(manifest.contributors, manifest.maintainers);
+    const normalizedBugs = normalizeBugs(manifest.bugs);
+    const normalizedKeywords = normalizeKeywords(manifest.keywords);
+    const normalizedEngines = normalizeEngines(manifest.engines);
+    const normalizedOs = normalizeOs(manifest.os);
+    const normalizedCpu = normalizeCpu(manifest.cpu);
+    // holds the same object reference but renames the variable here
+    // so that it's simpler to cast it to the normalized type
+    const normalizedManifest = manifest;
+    if (normalizedAuthor) {
+        normalizedManifest.author = normalizedAuthor;
+    }
+    else {
+        delete normalizedManifest.author;
+    }
+    if (normalizedFunding) {
+        normalizedManifest.funding = normalizedFunding;
+    }
+    else {
+        delete normalizedManifest.funding;
+    }
+    if (normalizedContributors) {
+        normalizedManifest.contributors = normalizedContributors;
+    }
+    else {
+        delete normalizedManifest.contributors;
+    }
+    if (normalizedBugs) {
+        normalizedManifest.bugs = normalizedBugs;
+    }
+    else {
+        delete normalizedManifest.bugs;
+    }
+    if (normalizedKeywords) {
+        normalizedManifest.keywords = normalizedKeywords;
+    }
+    else {
+        delete normalizedManifest.keywords;
+    }
+    if (normalizedEngines) {
+        normalizedManifest.engines = normalizedEngines;
+    }
+    else {
+        delete normalizedManifest.engines;
+    }
+    if (normalizedOs) {
+        normalizedManifest.os = normalizedOs;
+    }
+    else {
+        delete normalizedManifest.os;
+    }
+    if (normalizedCpu) {
+        normalizedManifest.cpu = normalizedCpu;
+    }
+    else {
+        delete normalizedManifest.cpu;
+    }
+    // Remove maintainers field if it exists in the raw manifest
+    // this can only happen if the manifest is of ManifestRegistry type
+    if ('maintainers' in normalizedManifest &&
+        normalizedManifest.maintainers) {
+        delete normalizedManifest.maintainers;
+        return normalizedManifest;
+    }
+    return normalizedManifest;
+};
+/**
+ * Type guard to check if a value is a {@link NormalizedManifest}.
+ */
+export const isNormalizedManifest = (o) => {
+    return (isManifest(o) &&
+        // given that all these values are optional and potentially undefined
+        // we only check their value content if they are present
+        ('author' in o ? isNormalizedContributorEntry(o.author) : true) &&
+        ('contributors' in o ?
+            isNormalizedContributors(o.contributors)
+            : true) &&
+        ('funding' in o ? isNormalizedFunding(o.funding) : true) &&
+        ('bugs' in o ? isNormalizedBugs(o.bugs) : true) &&
+        ('keywords' in o ? isNormalizedKeywords(o.keywords) : true) &&
+        ('engines' in o ? isNormalizedEngines(o.engines) : true) &&
+        ('os' in o ? isNormalizedOs(o.os) : true) &&
+        ('cpu' in o ? isNormalizedCpu(o.cpu) : true));
+};
+/**
+ * Given an unknown value, convert it to a {@link NormalizedManifest}.
+ */
+export const asNormalizedManifest = (m, from) => {
+    if (!isNormalizedManifest(m)) {
+        throw error('invalid normalized manifest', { found: m }, from ?? asNormalizedManifest);
+    }
+    return m;
+};
+/**
+ * Given an unknown value, convert it to a {@link ManifestRegistry}.
+ */
 export const asManifestRegistry = (m, from) => {
     if (!isManifestRegistry(m)) {
         throw error('invalid registry manifest', { found: m }, from ?? asManifestRegistry);
     }
     return m;
 };
+/**
+ * Type guard to check if a value is a {@link NormalizedManifestRegistry}.
+ */
+export const isNormalizedManifestRegistry = (o) => {
+    return isNormalizedManifest(o) && isManifestRegistry(o);
+};
+/**
+ * Given an unknown value, convert it to a {@link NormalizedManifestRegistry}.
+ */
+export const asNormalizedManifestRegistry = (m, from) => {
+    if (!isNormalizedManifestRegistry(m)) {
+        throw error('invalid normalized manifest registry', { found: m }, from ?? asNormalizedManifestRegistry);
+    }
+    return m;
+};
+/**
+ * Expands a normalized contributor entry by converting the
+ * in-memory symbols to their plain values.
+ */
+const expandNormalizedContributorEntrySymbols = (c) => {
+    return {
+        ...c,
+        writeAccess: c[kWriteAccess],
+        isPublisher: c[kIsPublisher],
+    };
+};
+/**
+ * Walks a normalized manifest and expands any symbols found
+ * in the `author` and `contributors` fields.
+ */
+export const expandNormalizedManifestSymbols = (m) => {
+    const res = { ...m };
+    if (isNormalizedContributorEntry(m.author)) {
+        res.author = expandNormalizedContributorEntrySymbols(m.author);
+    }
+    if (isNormalizedContributors(m.contributors)) {
+        res.contributors = m.contributors.map(expandNormalizedContributorEntrySymbols);
+    }
+    return res;
+};
 export const assertManifest = m => {
     asManifest(m, assertManifest);
 };
@@ -70,7 +679,7 @@ export const assertManifestRegistry = m => {
     asManifestRegistry(m, assertManifestRegistry);
 };
 export const isPackument = (p) => {
-    if (!isObj(p) || typeof p.name !== 'string')
+    if (!isObject(p) || typeof p.name !== 'string')
         return false;
     const { versions, 'dist-tags': distTags, time } = p;
     return (isRecordStringString(distTags) &&