@roostorg/types 1.0.49

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@roostorg/types",
+  "type": "module",
+  "version": "1.0.49",
+  "description": "Shared types across Cove services",
+  "module": "transpiled/index.js",
+  "typings": "./transpiled/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test transpiled/test_scripts/"
+  },
+  "author": "",
+  "files": [
+    "transpiled"
+  ],
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.3.1",
+    "typescript": "^4.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./transpiled/index.js",
+      "types": "./transpiled/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "date-fns": "^2.29.3",
+    "type-fest": "^4.3.2"
+  }
+}

package/transpiled/index.d.ts

@@ -0,0 +1,199 @@
+import { type Opaque } from 'type-fest';
+type Satisfies<T extends U, U> = T;
+export declare const ScalarTypes: {
+    USER_ID: "USER_ID";
+    ID: "ID";
+    STRING: "STRING";
+    BOOLEAN: "BOOLEAN";
+    NUMBER: "NUMBER";
+    AUDIO: "AUDIO";
+    IMAGE: "IMAGE";
+    VIDEO: "VIDEO";
+    DATETIME: "DATETIME";
+    GEOHASH: "GEOHASH";
+    RELATED_ITEM: "RELATED_ITEM";
+    URL: "URL";
+    POLICY_ID: "POLICY_ID";
+};
+export type ScalarTypes = typeof ScalarTypes;
+export type ScalarType = keyof typeof ScalarTypes;
+export declare const ContainerTypes: {
+    ARRAY: "ARRAY";
+    MAP: "MAP";
+};
+export type ContainerTypes = typeof ContainerTypes;
+export type ContainerType = keyof ContainerTypes;
+type ScalarTypeRuntimeTypeMapping = Satisfies<{
+    [ScalarTypes.STRING]: string;
+    [ScalarTypes.ID]: string;
+    [ScalarTypes.USER_ID]: ItemIdentifier;
+    [ScalarTypes.GEOHASH]: string;
+    [ScalarTypes.URL]: UrlString;
+    [ScalarTypes.BOOLEAN]: boolean;
+    [ScalarTypes.NUMBER]: number;
+    [ScalarTypes.DATETIME]: DateString;
+    [ScalarTypes.AUDIO]: {
+        url: string;
+    };
+    [ScalarTypes.IMAGE]: {
+        url: string;
+    };
+    [ScalarTypes.VIDEO]: {
+        url: string;
+    };
+    [ScalarTypes.RELATED_ITEM]: RelatedItem;
+    [ScalarTypes.POLICY_ID]: string;
+}, {
+    [K in ScalarType]: unknown;
+}>;
+type ContainerTypeRuntimeTypeMapping<ValueType extends ScalarType = ScalarType> = Satisfies<{
+    [ContainerTypes.ARRAY]: ScalarTypeRuntimeType<ValueType>[];
+    [ContainerTypes.MAP]: {
+        [key: string]: ScalarTypeRuntimeType<ValueType>;
+    };
+}, {
+    [K in ContainerType]: unknown;
+}>;
+export type ScalarTypeRuntimeType<T extends ScalarType = ScalarType> = ScalarTypeRuntimeTypeMapping[T];
+export type FieldType = ScalarType | ContainerType;
+export type Container<T extends ContainerType> = Readonly<{
+    containerType: T;
+    keyScalarType: Satisfies<{
+        [ContainerTypes.MAP]: ScalarType;
+        [ContainerTypes.ARRAY]: null;
+    }, {
+        [K in ContainerType]: unknown;
+    }>[T];
+    valueScalarType: ScalarType;
+}>;
+export type Field<T extends FieldType = FieldType> = {
+    [Type in ScalarType]: {
+        name: string;
+        type: Type;
+        required: boolean;
+        container: null;
+    };
+}[ScalarType & T] | {
+    [Type in ContainerType]: {
+        name: string;
+        type: Type;
+        required: boolean;
+        container: Container<Type>;
+    };
+}[ContainerType & T];
+export type ContainerTypeRuntimeType<T extends ContainerType, V extends ScalarType = ScalarType> = ContainerTypeRuntimeTypeMapping<V>[T];
+export type FieldTypeRuntimeType<T extends FieldType, ContainerValueType extends ScalarType = ScalarType> = ScalarTypeRuntimeType<T & ScalarType> | ContainerTypeRuntimeType<T & ContainerType, ContainerValueType>;
+/**
+ * In the case of scalar fields, this returns the ScalarType of their single
+ * value; in the case of container fields, it gives the type of the scalars in
+ * the container (i.e., the ScalarType for the array's items or map's values).
+ * With container fields, we don't track details at the type level of what
+ * scalars they contain, so this type assumes it could be anything.
+ */
+export type FieldScalarType<T extends FieldType> = T extends ScalarType ? T : ScalarType;
+/**
+ * A TaggedScalar holds a scalar value, along with a label identifying its
+ * ScalarTypes. This label is necessary because not all scalar values have a
+ * unique js runtime representation (e.g., ScalarTypes.STRING and
+ * ScalarTypes.GEOHASH are both represented as strings), so, without the label,
+ * we wouldn't know unambiguously which ScalarType a value belongs to, which we
+ * need sometimes (e.g., when deciding whether we can pass it to a signal).
+ *
+ * For why this type is written this way, see
+ * https://github.com/protegoapi/protego/pull/20#discussion_r883974513
+ */
+type EnumScalarType = ScalarTypes['STRING'] | ScalarTypes['NUMBER'];
+export type TaggedScalar<T extends ScalarType> = {
+    [K in ScalarType]: {
+        type: K;
+        value: ScalarTypeRuntimeType<K>;
+    } | (K extends EnumScalarType ? {
+        type: K;
+        value: ScalarTypeRuntimeType<K>;
+        enum: readonly ScalarTypeRuntimeType<K>[];
+        ordered: boolean;
+    } : never);
+}[T];
+export declare function isContainerField(it: Field): it is Field<ContainerType>;
+export declare function isContainerType(it: FieldType): it is ContainerType;
+export declare function getScalarType<T extends FieldType>(it: Field<T>): FieldScalarType<T>;
+export declare function isMediaType(it: ScalarType): boolean;
+export declare function isMediaValue<T extends ScalarType>(it: TaggedScalar<T>): it is TaggedScalar<T & (ScalarTypes['IMAGE'] | ScalarTypes['VIDEO'] | ScalarTypes['AUDIO'])>;
+/**
+ * Takes an array of strings and returns an object with a property for each
+ * string in the array, where the string is used as both the name and value for
+ * the property.
+ *
+ * This is useful to get type safety and automatic refactoring in some cases.
+ * E.g., imagine you're setting the default value for a field on a Sequelize
+ * model. Let's say the field can have three legal values: 'a', 'b', or 'c'.
+ * So, you'll initialize the model with some config object for the field, like
+ * `{ defaultValue: 'a' }`. Now, the type that this `defaultValue` key expects
+ * will be very vague -- likely `string` or maybe even `any` -- because it was
+ * defined by Sequelize and doesn't know about your field's specific legal
+ * values. Therefore, you could write `{ defaultValue: 'invalid' }` and TS
+ * wouldn't complain; moreover, even if you wrote `{ defaultValue: 'a' }`, which
+ * would be correct at the time, a rename on the value 'a' would not
+ * automatically rename the value here, because they're not linked by type.
+ *
+ * To fix these issues, it can be very helpful to have an object like
+ * `const legalValues = { 'a': 'a', 'b': 'b', 'c': 'c' };` because, then,
+ * you can do `{ defaultValues: legalValues.a }`, and you're guaranteed a typo-
+ * free and rename-friendly value. That `legalValues` object is what this
+ * function makes.
+ *
+ * Obviously, such an object is similar to a TS enum (hence this function's
+ * name). The key difference, though, is that the values in this object are
+ * typed as string literals, whereas the value for each case in an enum is
+ * treated by the type system as intentionally opaque. So, having that
+ * visibility in an 'enum-like' can help a lot with assignability, when the
+ * source value is a string literal type (rather than the source having to have
+ * been constructed with the same enum).
+ *
+ * We also exploit this for assigning values that come in from GraphQL. The
+ * GraphQL value is an enum; we want to use a different type in our inner layers
+ * (which shouldn't be coupled to GraphQL); but, if our internal type were an
+ * enum, the GraphQL enum wouldn't be assignable to it (even if their runtime
+ * values match). However, if the internal type is an "enum like", then TS will
+ * allow GraphQL enum to be assignable to it iff the enum's runtime values are
+ * legal values in the enum like.
+ */
+export declare function makeEnumLike<T extends string>(strings: readonly T[]): { [K in T]: K; };
+export declare const hiveProjectNames: readonly ["Visual", "Text", "Speech", "OCR", "Demographic"];
+export type HiveProjectName = (typeof hiveProjectNames)[number];
+export declare function isHiveProjectName(name: string): name is HiveProjectName;
+export type SignalSubcategory = {
+    id: string;
+    label: string;
+    description?: string;
+    children: SignalSubcategory[];
+};
+export type DateString = Opaque<string, 'DateString'>;
+export declare function parseDateString(it: DateString): Date;
+/**
+ * Returns a DateString if the input string can be parsed
+ * as a date; else undefined. Accepts strings in a rather limited set
+ * of formats for now. (See {@link parseJSON} docs for details.)
+ */
+export declare function makeDateString(it: string): DateString | undefined;
+export type RelatedItem = Satisfies<{
+    id: string;
+    typeId: string;
+    name?: string;
+}, ItemIdentifier>;
+/**
+ * UrlString represents a string that's known to be parsable into a valid URL;
+ * analogous to DateString.
+ */
+export type UrlString = Opaque<string, 'UrlString'>;
+export type ItemIdentifier = Readonly<{
+    id: string;
+    typeId: string;
+}>;
+export declare const ItemTypeKind: {
+    CONTENT: "CONTENT";
+    THREAD: "THREAD";
+    USER: "USER";
+};
+export type ItemTypeKind = keyof typeof ItemTypeKind;
+export {};

package/transpiled/index.js

@@ -0,0 +1,112 @@
+import { isValid, parseJSON } from 'date-fns';
+// TODO: Representing geographical _points_ and _areas_ with the same scalar
+// type is probably not ideal.
+//
+// NB: the ID type refers to ids for any type of entity, but USER_ID should be
+// used instead for fields that hold ids of users protego might know about. E.g.,
+// imagine a `Message` content type. Both the `to` and `from` fields could hold
+// ScalarTypes.USER_IDs, and then a rule could flag the message if _either_ the
+// sender or the recipient satisfies some condition (after passing the user id
+// to a user-related signal).
+export const ScalarTypes = makeEnumLike([
+    'USER_ID',
+    'ID',
+    'STRING',
+    'BOOLEAN',
+    'NUMBER',
+    'AUDIO',
+    'IMAGE',
+    'VIDEO',
+    'DATETIME',
+    'GEOHASH',
+    'RELATED_ITEM',
+    'URL',
+    'POLICY_ID',
+]);
+export const ContainerTypes = makeEnumLike(['ARRAY', 'MAP']);
+const containerTypes = new Set(Object.values(ContainerTypes));
+export function isContainerField(it) {
+    return isContainerType(it.type);
+}
+export function isContainerType(it) {
+    return containerTypes.has(it);
+}
+export function getScalarType(it) {
+    return (isContainerField(it) ? it.container.valueScalarType : it.type);
+}
+export function isMediaType(it) {
+    return (it === ScalarTypes.AUDIO ||
+        it === ScalarTypes.VIDEO ||
+        it === ScalarTypes.IMAGE);
+}
+export function isMediaValue(it) {
+    return isMediaType(it.type);
+}
+/**
+ * Takes an array of strings and returns an object with a property for each
+ * string in the array, where the string is used as both the name and value for
+ * the property.
+ *
+ * This is useful to get type safety and automatic refactoring in some cases.
+ * E.g., imagine you're setting the default value for a field on a Sequelize
+ * model. Let's say the field can have three legal values: 'a', 'b', or 'c'.
+ * So, you'll initialize the model with some config object for the field, like
+ * `{ defaultValue: 'a' }`. Now, the type that this `defaultValue` key expects
+ * will be very vague -- likely `string` or maybe even `any` -- because it was
+ * defined by Sequelize and doesn't know about your field's specific legal
+ * values. Therefore, you could write `{ defaultValue: 'invalid' }` and TS
+ * wouldn't complain; moreover, even if you wrote `{ defaultValue: 'a' }`, which
+ * would be correct at the time, a rename on the value 'a' would not
+ * automatically rename the value here, because they're not linked by type.
+ *
+ * To fix these issues, it can be very helpful to have an object like
+ * `const legalValues = { 'a': 'a', 'b': 'b', 'c': 'c' };` because, then,
+ * you can do `{ defaultValues: legalValues.a }`, and you're guaranteed a typo-
+ * free and rename-friendly value. That `legalValues` object is what this
+ * function makes.
+ *
+ * Obviously, such an object is similar to a TS enum (hence this function's
+ * name). The key difference, though, is that the values in this object are
+ * typed as string literals, whereas the value for each case in an enum is
+ * treated by the type system as intentionally opaque. So, having that
+ * visibility in an 'enum-like' can help a lot with assignability, when the
+ * source value is a string literal type (rather than the source having to have
+ * been constructed with the same enum).
+ *
+ * We also exploit this for assigning values that come in from GraphQL. The
+ * GraphQL value is an enum; we want to use a different type in our inner layers
+ * (which shouldn't be coupled to GraphQL); but, if our internal type were an
+ * enum, the GraphQL enum wouldn't be assignable to it (even if their runtime
+ * values match). However, if the internal type is an "enum like", then TS will
+ * allow GraphQL enum to be assignable to it iff the enum's runtime values are
+ * legal values in the enum like.
+ */
+export function makeEnumLike(strings) {
+    return Object.fromEntries(strings.map((it) => [it, it]));
+}
+export const hiveProjectNames = [
+    'Visual',
+    'Text',
+    'Speech',
+    'OCR',
+    'Demographic',
+];
+export function isHiveProjectName(name) {
+    return hiveProjectNames.includes(name);
+}
+export function parseDateString(it) {
+    return new Date(it);
+}
+/**
+ * Returns a DateString if the input string can be parsed
+ * as a date; else undefined. Accepts strings in a rather limited set
+ * of formats for now. (See {@link parseJSON} docs for details.)
+ */
+export function makeDateString(it) {
+    const potentialDate = parseJSON(it);
+    // check if the parsing succeeded; return accordingly
+    return isValid(potentialDate)
+        ? potentialDate.toISOString()
+        : undefined;
+}
+export const ItemTypeKind = makeEnumLike(['CONTENT', 'THREAD', 'USER']);

package/transpiled/test_scripts/makeDateStringTest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/transpiled/test_scripts/makeDateStringTest.test.js

@@ -0,0 +1,24 @@
+// We allow the test files, and only the test files, to reference node types cuz
+// we don't run these in the browser.
+/// <reference types="node" />
+import * as assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { makeDateString } from '../index.js';
+const stringsAndExpectedResults = {
+    '': undefined,
+    abc: undefined,
+    '1': undefined,
+    '2023-04-12T19:47:09.406Z': '2023-04-12T19:47:09.406Z',
+    '2023.0.1.01': undefined,
+    '2023.01.01': undefined,
+    '2023-04-12T19:47:09.40604Z': '2023-04-12T19:47:09.406Z',
+    '2023-04-12T19:47:09.4Z': '2023-04-12T19:47:09.400Z',
+};
+describe('makeDateString', () => {
+    it('should properly handle inputs', () => {
+        Object.entries(stringsAndExpectedResults).map(([key, value]) => {
+            const result = makeDateString(key);
+            assert.ok(result === value, `makeDateString('${key}') was expected to be ${value}, but instead was ${result}.`);
+        });
+    });
+});