@cyberismo/data-handler 0.0.2

package/src/utils/resource-utils.ts

@@ -0,0 +1,180 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+// node
+import { join, parse, sep } from 'node:path';
+
+import type { Project } from '../containers/project.js';
+import { stripExtension } from './file-utils.js';
+
+// Resource name parts are:
+// - prefix; name of the project this resource is part of
+// - type; type of resource; in plural
+// - identifier; unique name (within a project/module) for the resource
+export interface ResourceName {
+  prefix: string;
+  type: string; // todo: should be a ResourceFolderType
+  identifier: string;
+}
+
+// Indexes of resource name parts
+const PREFIX_INDEX = 0;
+const TYPE_INDEX = 1;
+const IDENTIFIER_INDEX = 2;
+// Valid resource name has three parts
+const RESOURCE_NAME_PARTS = 3;
+
+// Checks if name is valid (3 parts, separated by '/').
+export function isResourceName(name: string): boolean {
+  const partsCount = name.split('/').length;
+  return partsCount === RESOURCE_NAME_PARTS;
+}
+
+/**
+ * Returns resource name parts (project prefix, type in plural, name of the resource).
+ * @param resourceName Name of the resource (e.g. <prefix>/<type>/<name>)
+ * @param strict If true, does not allow names without 'prefix' and 'type'.
+ * @throws if 'resourceName' is not valid resource name.
+ * @returns resource name parts: project or module prefix, resource type (plural) and actual name of the resource.
+ * @todo: In the future, switch the default value of 'strict' to true. Only in certain cases should we accept names with just 'identifier'.
+ */
+export function resourceName(
+  resourceName: string,
+  strict: boolean = false,
+): ResourceName {
+  const parts = resourceName.split('/');
+  // just resource identifier - type and prefix are unknown
+  if (parts.length === 1 && parts.at(0) !== '') {
+    if (strict) {
+      throw new Error(`Name '${resourceName}' is not valid resource name`);
+    }
+    return {
+      prefix: '',
+      type: '',
+      identifier: resourceName,
+    };
+  }
+  // resource name
+  if (parts.length === RESOURCE_NAME_PARTS) {
+    return {
+      prefix: parts[PREFIX_INDEX],
+      type: parts[TYPE_INDEX],
+      identifier: parse(parts[IDENTIFIER_INDEX]).name,
+    };
+  }
+  // other formats are not accepted
+  if (resourceName === '') {
+    throw new Error('Must define resource name to query its details');
+  }
+  throw new Error(`Name '${resourceName}' is not valid resource name`);
+}
+
+/**
+ * Converts resource name to path.
+ * @param project Project
+ * @param resourceName Name of the resource (e.g. <prefix>/<type>/<name>)
+ * @returns path to resource metadata file
+ */
+export function resourceNameToPath(
+  project: Project,
+  resourceName: ResourceName,
+): string {
+  if (project.projectPrefix === resourceName.prefix) {
+    return join(
+      project.paths.resourcesFolder,
+      resourceName.type,
+      resourceName.identifier + '.json',
+    );
+  } else if (resourceName.prefix !== '') {
+    return join(
+      project.paths.modulesFolder,
+      resourceName.prefix,
+      resourceName.type,
+      resourceName.identifier + '.json',
+    );
+  }
+  throw new Error('resourceName does not contain prefix');
+}
+
+/**
+ * Resource metadata file path to resource name (e.g. <prefix>/<type>/<name>)
+ * @param project Project where resource is in
+ * @param path Path to resource metadata file
+ * @returns Resource name (<prefix>/<type>/<name>)
+ */
+export function pathToResourceName(
+  project: Project,
+  path: string,
+): ResourceName {
+  const parts = path.split(sep);
+  const modulesIndex = parts.lastIndexOf('modules');
+  const localIndex = parts.lastIndexOf('local');
+  // Check that either 'local' or 'modules' is included in path (but not both).
+  // And after that there is required amount of parts.
+  if (
+    (modulesIndex === -1 && localIndex === -1) ||
+    (modulesIndex !== -1 && localIndex !== -1) ||
+    (modulesIndex !== -1 &&
+      localIndex === 1 &&
+      parts.length === modulesIndex + 3) ||
+    (modulesIndex === -1 &&
+      localIndex !== -1 &&
+      parts.length === localIndex + 2)
+  ) {
+    throw new Error(`invalid path: ${path}`);
+  }
+  // Finally check that all relevant parts are defined.
+  const prefix =
+    modulesIndex !== -1 ? parts.at(modulesIndex + 1) : project.projectPrefix;
+  const typeIndex = modulesIndex !== -1 ? modulesIndex + 2 : localIndex + 1;
+  const identifierIndex =
+    modulesIndex !== -1 ? modulesIndex + 3 : localIndex + 2;
+  const type = parts.at(typeIndex);
+  const identifier = stripExtension(parts.at(identifierIndex)!);
+  if (!identifier || !type || !prefix) {
+    throw new Error(`invalid path: ${path}`);
+  }
+  return {
+    prefix: prefix,
+    type: type,
+    identifier: identifier,
+  };
+}
+
+/**
+ * Returns ResourceName as a single string.
+ * @param resourceName Resource name to convert.
+ * @returns resource name as a single string.
+ * @note that valid resource names are: empty string, identifier alone and prefix/type/identifier combination.
+ */
+export function resourceNameToString(resourceName: ResourceName): string {
+  if (!resourceName.prefix && !resourceName.type && !resourceName.identifier) {
+    return '';
+  }
+  if (resourceName.identifier === '') {
+    throw new Error(`Not a valid resource name. Identifier is missing.`);
+  }
+  if (
+    resourceName.prefix &&
+    resourceName.identifier &&
+    resourceName.type === ''
+  ) {
+    throw new Error(`Not a valid resource name. Type is missing.`);
+  }
+  if (
+    resourceName.prefix === '' &&
+    resourceName.identifier &&
+    resourceName.type
+  ) {
+    throw new Error(`Not a valid resource name. Prefix is missing.`);
+  }
+  return resourceName.prefix && resourceName.type && resourceName.prefix
+    ? `${resourceName.prefix}/${resourceName.type}/${resourceName.identifier}`
+    : `${resourceName.identifier}`;
+}

package/src/utils/sanitize-svg.ts

@@ -0,0 +1,46 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import createDOMPurify, { type WindowLike } from 'dompurify';
+import { Buffer } from 'buffer';
+import { JSDOM } from 'jsdom';
+
+const window = new JSDOM('').window as unknown as Window;
+
+// Remove SVG size to make it scale in the application properly
+const removeSvgWidthAndHeight = (node: Element) => {
+  if (node.nodeName === 'svg') {
+    node.removeAttribute('width');
+    node.removeAttribute('height');
+  }
+};
+
+/**
+ * Sanitize an SVG Buffer and return a base64-encoded string
+ * @param buffer - SVG content as a Buffer
+ * @returns base64-encoded sanitized SVG string
+ */
+export function sanitizeSvgBase64(buffer: Buffer): string {
+  const DOMPurify = createDOMPurify(window as unknown as WindowLike);
+
+  const dirty = buffer.toString('utf-8');
+
+  DOMPurify.setConfig({ USE_PROFILES: { svg: true } });
+  DOMPurify.addHook('afterSanitizeAttributes', removeSvgWidthAndHeight);
+
+  let cleaned = DOMPurify.sanitize(dirty);
+
+  // Remove link titles, quick fix for Clingraph/Graphviz generated titles for links that are quite strange
+  cleaned = cleaned.replace(/\s*xlink:title=(["']).*?\1/g, '');
+
+  return Buffer.from(cleaned, 'utf-8').toString('base64');
+}

package/src/utils/user-preferences.ts

@@ -0,0 +1,126 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { formatJson } from './json.js';
+import { dirname } from 'path';
+
+export interface UserPreferencesObject {
+  editCommand: {
+    [platform: string]: {
+      command: string;
+      args: string[];
+    };
+  };
+  attachmentEditors: {
+    [platform: string]: {
+      mimeType: string;
+      command: string;
+    }[];
+  };
+}
+/**
+ * The class checks if the preferences file exists when instantiated, and if not, creates it with a default JSON object.
+ * The getPreferences() method simply reads and parses the file to return the preferences object.
+ */
+export class UserPreferences {
+  // If preferences do not exist, they are initialised
+  // with these defaults.
+  static defaults = {
+    editCommand: {
+      darwin: {
+        command: 'code',
+        args: ['{{cardContentPath}}', '{{cardJsonPath}}'],
+      },
+      linux: {
+        command: 'vi',
+        args: ['{{cardContentPath}}', '{{cardJsonPath}}'],
+      },
+      win32: {
+        command: 'notepad.exe',
+        args: ['{{cardContentPath}}', '{{cardJsonPath}}'],
+      },
+    },
+    attachmentEditors: {
+      darwin: [
+        {
+          mimeType: 'image/png',
+          command: "open -a draw.io '{{attachmentPath}}'",
+        },
+        {
+          mimeType: 'image/svg+xml',
+          command: "open -a draw.io '{{attachmentPath}}'",
+        },
+        {
+          mimeType: 'application/pdf',
+          command: 'open -a Preview "{{attachmentPath}}"',
+        },
+      ],
+      linux: [
+        {
+          mimeType: 'image/png',
+          command: 'drawio {{attachmentPath}}',
+        },
+        {
+          mimeType: 'image/svg+xml',
+          command: 'drawio {{attachmentPath}}',
+        },
+      ],
+      win32: [
+        {
+          mimeType: 'text/plain',
+          command: 'notepad.exe {{attachmentPath}}',
+        },
+        {
+          mimeType: 'image/png',
+          command:
+            '"C:\\Program Files\\draw.io\\draw.io.exe" "{{attachmentPath}}"',
+        },
+        {
+          mimeType: 'image/svg+xml',
+          command:
+            '"C:\\Program Files\\draw.io\\draw.io.exe" "{{attachmentPath}}"',
+        },
+      ],
+    },
+  };
+
+  constructor(private prefsFilePath: string) {
+    if (!existsSync(this.prefsFilePath)) {
+      // Create the preferences directory based on prefsFilePath dirname
+      const prefsDir = dirname(this.prefsFilePath);
+
+      try {
+        if (!existsSync(prefsDir)) {
+          mkdirSync(prefsDir, { recursive: true });
+        }
+        // File does not exist, create it with default content
+        writeFileSync(this.prefsFilePath, formatJson(UserPreferences.defaults));
+      } catch (error) {
+        throw new Error(
+          `Error creating preferences file '${this.prefsFilePath}': ${error}`,
+        );
+      }
+    }
+  }
+
+  public getPreferences(): UserPreferencesObject {
+    // Read and parse the preferences file
+    try {
+      return JSON.parse(readFileSync(this.prefsFilePath, 'utf8'));
+    } catch (error) {
+      throw new Error(
+        `Error reading preferences file '${this.prefsFilePath}': ${error}`,
+      );
+    }
+  }
+}

package/src/utils/validate.ts

@@ -0,0 +1,66 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { type Schema, Validator } from 'jsonschema';
+import { DHValidationError, SchemaNotFound } from '../exceptions/index.js';
+import { schemas } from '@cyberismo/resources';
+
+/**
+ * Validates a JSON object against a schema
+ * @param object The object to validate
+ * @param schemaId The id of the schema to validate against
+ * @param validator An optional validator to use. If validator is not provided or does not contain any schemas, project schemas will be used
+ * @returns The object casted to the type T if it is valid
+ * @throws DHValidationError if the object is not valid
+ * @throws SchemaNotFound if the schema with the given id is not found
+ */
+export function validateJson<T>(
+  object: unknown,
+  options: {
+    schemaId?: string;
+    schema?: Schema;
+    validator?: Validator;
+  },
+): T {
+  const { schemaId, schema } = options;
+  let validator = options.validator;
+
+  if (!schema && !schemaId) {
+    throw new Error('Must either specify schema or schemaId');
+  }
+
+  if (!validator) {
+    validator = new Validator();
+    for (const schema of schemas) {
+      validator.addSchema(schema, schema.$id);
+    }
+  }
+
+  let jsonSchema: Schema | undefined;
+
+  if (schema) {
+    jsonSchema = schema;
+  } else {
+    jsonSchema = Object.values(validator.schemas).find(
+      (s) => s.$id === schemaId,
+    );
+  }
+
+  if (!jsonSchema) {
+    throw new SchemaNotFound(`Schema with id ${schemaId} not found`);
+  }
+  const result = validator.validate(object, jsonSchema);
+  if (!result.valid) {
+    throw new DHValidationError('Validation failed', result.errors);
+  }
+  // we know that the object is valid, so we can safely cast it to T
+  return object as T;
+}

package/src/utils/value-utils.ts

@@ -0,0 +1,189 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation.
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+  details. You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import type { DataType } from '../interfaces/resource-interfaces.js';
+import { isBigInt } from '../utils/common-utils.js';
+import * as EmailValidator from 'email-validator';
+
+const SHORT_TEXT_MAX_LENGTH = 80;
+
+/**
+ * Checks if conversion 'from' 'to' can be done.
+ * @param from Data type to convert from
+ * @param to  Data type to convert to
+ * @returns true if conversion can be done, false otherwise.
+ */
+export function allowed(from: DataType, to: DataType) {
+  // Converting from strings is fine, except to enum.
+  if (from === 'longText' || from === 'shortText') {
+    switch (to) {
+      case 'boolean':
+      case 'date':
+      case 'dateTime':
+      case 'integer':
+      case 'list':
+      case 'longText':
+      case 'number':
+      case 'person':
+      case 'shortText':
+        return true;
+      default:
+        return false;
+    }
+  }
+  // Converting from<->to number formats is fine
+  if (
+    (from === 'number' && to === 'integer') ||
+    (from === 'integer' && to === 'number')
+  ) {
+    return true;
+  }
+
+  // Converting to strings is fine
+  if (to === 'shortText' || to === 'longText') {
+    return true;
+  }
+
+  // Converting from<->to date formats is fine
+  if (
+    (from === 'dateTime' && to === 'date') ||
+    (from === 'date' && to === 'dateTime')
+  ) {
+    return true;
+  }
+  // Everything else is forbidden.
+  return false;
+}
+
+/**
+ * Converts number value to other data types.
+ * @param value Value to convert
+ * @param to Date type to which value is converted to
+ * @returns converted value, or null if cannot convert
+ * Allowed conversions are
+ *  date -> dateTime
+ *  dateTime -> date
+ *  date/dateTime -> shortText/longText
+ */
+export function fromDate<T>(value: T, to: DataType) {
+  if (to === 'date') {
+    const tempDate = new Date(value as Date);
+    return new Date(tempDate).toISOString().slice(0, 10);
+  }
+  if (to === 'dateTime') {
+    const tempDate = new Date(value as Date);
+    return new Date(tempDate).toISOString();
+  }
+  if (to === 'longText' || to === 'shortText') {
+    return String(value);
+  }
+  return null;
+}
+
+/**
+ * Converts number value to other data types.
+ * @param value Value to convert
+ * @param to Date type to which value is converted to
+ * @returns converted value, or null if cannot convert
+ * Allowed conversions are
+ *  integer -> number
+ *  number -> integer
+ *  number/integer -> shortText
+ *  number/integer -> longText
+ */
+export function fromNumber<T>(value: T, to: DataType) {
+  if (to === 'integer') {
+    return Math.trunc(value as number);
+  }
+  if (to === 'longText') {
+    return String(value);
+  }
+  if (to === 'number') {
+    return Number(value);
+  }
+  if (to === 'shortText') {
+    const tempString = String(value);
+    return tempString.length > SHORT_TEXT_MAX_LENGTH ? null : tempString;
+  }
+  return null;
+}
+
+/**
+ * Converts string value to other data types.
+ * @param value Value to convert
+ * @param to Date type to which value is converted to
+ * @returns converted value, or null if cannot convert
+ * Allowed conversions are
+ *  longText -> shortText
+ *  shortText -> longText
+ *  longText/shortText -> integer
+ *  longText/shortText -> number
+ *  longText/shortText -> list
+ *  longText/shortText -> date/dateTime
+ *  longText/shortText -> boolean
+ */
+export function fromString<T>(value: T, to: DataType) {
+  switch (to) {
+    case 'boolean': {
+      if (value === 'true') return true;
+      if (value === 'false') return false;
+      return null;
+    }
+    case 'date': {
+      try {
+        const tempDate = new Date((value as string) + 'Z').toUTCString();
+        return new Date(tempDate).toISOString().slice(0, 10);
+      } catch {
+        return null;
+      }
+    }
+    case 'dateTime': {
+      try {
+        const tempDate = new Date((value as string) + 'Z').toUTCString();
+        return new Date(tempDate).toISOString();
+      } catch {
+        return null;
+      }
+    }
+    case 'integer': {
+      if (isBigInt(value as string)) {
+        return BigInt(value as string);
+      }
+      const tempInt = parseInt(value as string);
+      return isNaN(tempInt) ? null : tempInt;
+    }
+    case 'list': {
+      return (value as string).split(',');
+    }
+    case 'longText': {
+      return value;
+    }
+    case 'number': {
+      if (isBigInt(value as string)) {
+        return BigInt(value as string);
+      }
+      const tempNumber = parseFloat(value as string);
+      return isNaN(tempNumber) ? null : tempNumber;
+    }
+    case 'person': {
+      if (EmailValidator.validate(value as string)) {
+        return String(value);
+      }
+      return null;
+    }
+    case 'shortText': {
+      return (value as string).length > SHORT_TEXT_MAX_LENGTH ? null : value;
+    }
+  }
+  return null;
+}