@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/src/packlets/common/helpers/conditions.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { mapResults, Result, succeed } from '@fgv/ts-utils';
+import * as Validate from '../validate';
+import { ConditionSetToken, ConditionToken } from '../conditions';
+
+/**
+ * The values needed to create a {@link ConditionToken | condition token}.
+ * @public
+ */
+export interface IConditionTokenParts {
+  qualifier?: string;
+  value: string;
+}
+
+/**
+ * Converts a {@link Helpers.IConditionTokenParts | the parts that make up a condition token} into
+ * a syntactically validated {@link ConditionToken | condition token}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildConditionToken({ qualifier, value }: IConditionTokenParts): Result<ConditionToken> {
+  return Validate.toConditionToken(qualifier ? `${qualifier}=${value}` : value);
+}
+
+/**
+ * Converts an array of {@link Helpers.IConditionTokenParts | condition token parts} into an array of
+ * syntactically validated {@link ConditionToken | condition tokens}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildConditionSetToken(
+  parts: ReadonlyArray<IConditionTokenParts>
+): Result<ConditionSetToken> {
+  return mapResults(parts.map(buildConditionToken)).onSuccess((tokens) =>
+    Validate.toConditionSetToken(tokens.join(','))
+  );
+}
+
+/**
+ * Parses a condition token string into its {@link Helpers.IConditionTokenParts | parts}.
+ * @param token - the token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseConditionTokenParts(token: string): Result<IConditionTokenParts> {
+  return Validate.toConditionToken(token).onSuccess((t) => {
+    const parts = t.split('=');
+    if (parts.length === 1) {
+      return succeed({ value: parts[0] });
+    }
+    return succeed({ qualifier: parts[0], value: parts[1] });
+  });
+}
+
+/**
+ * Parses a condition set token string into an array of {@link Helpers.IConditionTokenParts | condition token parts}.
+ * @param token - the conditions set token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseConditionSetTokenParts(token: string): Result<IConditionTokenParts[]> {
+  return mapResults(token.split(',').map(parseConditionTokenParts));
+}

package/src/packlets/common/helpers/context.ts

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { mapResults, Result, succeed } from '@fgv/ts-utils';
+import * as Validate from '../validate';
+import { ContextToken, ContextQualifierToken } from '../conditions';
+
+/**
+ * The values needed to create a {@link ContextQualifierToken | context qualifier token}.
+ * @public
+ */
+export interface IContextTokenParts {
+  qualifier?: string;
+  value: string;
+}
+
+/**
+ * Converts a {@link Helpers.IContextTokenParts | the parts that make up a context qualifier token} into
+ * a syntactically validated {@link ContextQualifierToken | context qualifier token}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildContextQualifierToken({
+  qualifier,
+  value
+}: IContextTokenParts): Result<ContextQualifierToken> {
+  return Validate.toContextQualifierToken(qualifier ? `${qualifier}=${value}` : value);
+}
+
+/**
+ * Converts an array of {@link Helpers.IContextTokenParts | context qualifier token parts} into a
+ * syntactically validated {@link ContextToken | context token}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildContextToken(parts: ReadonlyArray<IContextTokenParts>): Result<ContextToken> {
+  return mapResults(parts.map(buildContextQualifierToken)).onSuccess((tokens) =>
+    Validate.toContextToken(tokens.join('|'))
+  );
+}
+
+/**
+ * Parses a context qualifier token string into its {@link Helpers.IContextTokenParts | parts}.
+ * @param token - the token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseContextQualifierTokenParts(token: string): Result<IContextTokenParts> {
+  return Validate.toContextQualifierToken(token).onSuccess((t) => {
+    const parts = t.split('=');
+    if (parts.length === 1) {
+      return succeed({ value: parts[0] });
+    }
+    return succeed({ qualifier: parts[0], value: parts[1] });
+  });
+}
+
+/**
+ * Parses a context token string into an array of {@link Helpers.IContextTokenParts | context qualifier token parts}.
+ * @param token - the context token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseContextTokenParts(token: string): Result<IContextTokenParts[]> {
+  if (token === '') {
+    return succeed([]);
+  }
+  return mapResults(token.split('|').map((part) => parseContextQualifierTokenParts(part.trim())));
+}

package/src/packlets/common/helpers/index.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './conditions';
+export * from './context';
+export * from './qualifierDefaultValues';
+export * from './resources';

package/src/packlets/common/helpers/qualifierDefaultValues.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { mapResults, Result, succeed } from '@fgv/ts-utils';
+import * as Validate from '../validate';
+import { QualifierDefaultValueToken, QualifierDefaultValuesToken } from '../conditions';
+
+/**
+ * The values needed to create a {@link QualifierDefaultValueToken | qualifier default value token}.
+ * @public
+ */
+export interface IQualifierDefaultValueTokenParts {
+  qualifier: string;
+  value: string;
+}
+
+/**
+ * Converts a {@link Helpers.IQualifierDefaultValueTokenParts | the parts that make up a qualifier default value token} into
+ * a syntactically validated {@link QualifierDefaultValueToken | qualifier default value token}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildQualifierDefaultValueToken({
+  qualifier,
+  value
+}: IQualifierDefaultValueTokenParts): Result<QualifierDefaultValueToken> {
+  return Validate.toQualifierDefaultValueToken(`${qualifier}=${value}`);
+}
+
+/**
+ * Converts an array of {@link Helpers.IQualifierDefaultValueTokenParts | qualifier default value token parts} into a
+ * syntactically validated {@link QualifierDefaultValuesToken | qualifier default values token}.
+ * @param parts - the parts to convert
+ * @public
+ */
+export function buildQualifierDefaultValuesToken(
+  parts: ReadonlyArray<IQualifierDefaultValueTokenParts>
+): Result<QualifierDefaultValuesToken> {
+  return mapResults(parts.map(buildQualifierDefaultValueToken)).onSuccess((tokens) =>
+    Validate.toQualifierDefaultValuesToken(tokens.join('|'))
+  );
+}
+
+/**
+ * Parses a qualifier default value token string into its {@link Helpers.IQualifierDefaultValueTokenParts | parts}.
+ * @param token - the token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseQualifierDefaultValueTokenParts(
+  token: string
+): Result<IQualifierDefaultValueTokenParts> {
+  return Validate.toQualifierDefaultValueToken(token).onSuccess((t) => {
+    const [qualifier, value] = t.split('=');
+    return succeed({ qualifier, value });
+  });
+}
+
+/**
+ * Parses a qualifier default values token string into an array of {@link Helpers.IQualifierDefaultValueTokenParts | qualifier default value token parts}.
+ * @param token - the qualifier default values token string to parse.
+ * @returns `Success` with the parts if successful, `Failure` with an error message if not.
+ * @public
+ */
+export function parseQualifierDefaultValuesTokenParts(
+  token: string
+): Result<IQualifierDefaultValueTokenParts[]> {
+  if (token === '') {
+    return succeed([]);
+  }
+  return mapResults(token.split('|').map((part) => parseQualifierDefaultValueTokenParts(part.trim())));
+}

package/src/packlets/common/helpers/resources.ts

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { MessageAggregator, Result, mapResults, succeed } from '@fgv/ts-utils';
+import { ResourceId, ResourceName } from '../resources';
+import { toResourceId, toResourceName } from '../validate/resources';
+
+/**
+ * Splits a {@link ResourceId | resource id} into its component {@link ResourceName | resource names}.
+ *
+ * @param id - The ID to split.
+ * @returns `Success`with an array of {@link ResourceName | ResourceName} objects if the ID is valid, or
+ * `Failure` with an error message if not.
+ * @public
+ */
+export function splitResourceId(id: string | undefined): Result<ResourceName[]> {
+  if (id === undefined) {
+    return succeed([]);
+  }
+  return mapResults(id.split('.').map(toResourceName));
+}
+
+/**
+ * Joins a list of {@link ResourceId | resource ID} or {@link ResourceName | resource name} with
+ * to create a new {@link ResourceId | resource ID}. Fails if resulting ID is invalid or empty.
+ *
+ * @param base - The base name or ID to join.
+ * @param names - Additional names to join.
+ * @returns `Success` with the new ID if the base and names are valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function joinResourceIds(...ids: (string | undefined)[]): Result<ResourceId> {
+  const errors: MessageAggregator = new MessageAggregator();
+  const parts: ResourceName[] = [];
+  ids
+    .filter((id) => id !== '')
+    .forEach((id) => {
+      parts.push(...splitResourceId(id).aggregateError(errors).orDefault([]));
+    });
+  const id = parts.join('.');
+  return errors.returnOrReport(toResourceId(id));
+}
+
+/**
+ * Joins a list of {@link ResourceId | resource ID} or {@link ResourceName | resource name} with
+ * to create a new {@link ResourceId | resource ID}. Returns `undefined` if no names are defined.
+ *
+ * @param base - The base name or ID to join.
+ * @param names - Additional names to join.
+ * @returns `Success` with the new ID if the base and names are valid, `Success` with `undefined`
+ * if names were present, or `Failure` with an error message if the resulting id is invalid.
+ * @public
+ */
+export function joinOptionalResourceIds(...ids: (string | undefined)[]): Result<ResourceId | undefined> {
+  const errors: MessageAggregator = new MessageAggregator();
+  const parts: ResourceName[] = [];
+  ids
+    .filter((id) => id !== '')
+    .forEach((id) => {
+      parts.push(...splitResourceId(id).aggregateError(errors).orDefault([]));
+    });
+  const id = parts.join('.');
+  return errors.returnOrReport(id ? toResourceId(id) : succeed(undefined));
+}
+
+/**
+ * Gets the name for a resource ID.
+ * @param id - The resource ID to get the name for.
+ * @returns The resource name if found, or undefined if not.
+ * @public
+ */
+export function getNameForResourceId(id: string | undefined): Result<ResourceName> {
+  return splitResourceId(id).onSuccess((parts) => {
+    return parts.length > 0 ? succeed(parts[parts.length - 1]) : fail('Empty id has no name');
+  });
+}

package/src/packlets/common/index.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import * as Convert from './convert';
+import * as Helpers from './helpers';
+import * as Validate from './validate';
+
+export * from './conditions';
+export * from './resources';
+
+export { Convert, Helpers, Validate };

package/src/packlets/common/resources.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Brand } from '@fgv/ts-utils';
+
+/**
+ * Branded string representing a validated resource id.  A resource ID
+ * is a dot-separated sequence of resource names.
+ * @public
+ */
+export type ResourceId = Brand<string, 'ResourceId'>;
+
+/**
+ * Branded string representing a validated resource name.
+ * @public
+ */
+export type ResourceName = Brand<string, 'ResourceName'>;
+
+/**
+ * Branded number representing a validated resource index.
+ * @public
+ */
+export type ResourceIndex = Brand<number, 'ResourceIndex'>;
+
+/**
+ * Branded string representing a validated resource type name.
+ * @public
+ */
+export type ResourceTypeName = Brand<string, 'ResourceTypeName'>;
+
+/**
+ * Branded number representing a validated resource type index.
+ * @public
+ */
+export type ResourceTypeIndex = Brand<number, 'ResourceTypeIndex'>;
+
+/**
+ * Type representing the possible ways that a resource value can be merged into an existing resource.
+ * - 'augment' means that the new value should be merged into the existing value, with new properties added and existing properties updated.
+ * - 'delete' means that the existing values should be deleted.
+ * - 'replace' means that the new value should replace the existing value.
+ * @public
+ */
+export type ResourceValueMergeMethod = 'augment' | 'delete' | 'replace';
+
+/**
+ * Array of all possible {@link ResourceValueMergeMethod | resource merge type} values.
+ * @public
+ */
+export const allResourceValueMergeMethods: ResourceValueMergeMethod[] = ['augment', 'delete', 'replace'];
+
+/**
+ * The completeness of a resource candidate value.  A full value is one that
+ * contains all of the required properties for the resource type.  A partial
+ * value is one that contains some of the required properties for the resource
+ * type.
+ * @public
+ */
+export type CandidateCompleteness = 'full' | 'partial';