@knapsack/spec-utils 4.78.13--canary.5646.9581069.0 → 4.78.13

package/src/test-fixtures/index.ts

@@ -0,0 +1,2 @@
+export * from './basics.js';
+export * from './functions.js';

package/src/types.ts

@@ -0,0 +1,66 @@
+import ts from 'typescript';
+
+export type TypeInfoCommon = {
+  tsRawType: string;
+  isOptional?: boolean;
+  tsMetadata: {
+    typeFlags: Array<keyof typeof ts.TypeFlags>;
+    type: ts.Type;
+  };
+};
+export type TypeInfo =
+  | ({
+      type: 'string' | 'number' | 'boolean';
+    } & TypeInfoCommon)
+  | ({
+      type: 'stringLiteral';
+      value: string;
+    } & TypeInfoCommon)
+  | ({
+      type: 'numberLiteral';
+      value: number;
+    } & TypeInfoCommon)
+  | ({
+      type: 'union';
+      items: TypeInfo[];
+    } & TypeInfoCommon)
+  | ({
+      type: 'array';
+      items: TypeInfo;
+    } & TypeInfoCommon)
+  | ({
+      type: 'object';
+      properties: Record<string, SymbolInfo>;
+    } & TypeInfoCommon)
+  | ({
+      type: 'function';
+      parameters: SymbolInfo[];
+      returnType?: TypeInfo;
+      typeParameters?: TypeInfo[];
+    } & TypeInfoCommon)
+  | ({
+      type: 'class';
+      properties: Record<string, SymbolInfo>;
+      constructorParameters: SymbolInfo[];
+      constructorReturnType: TypeInfo;
+      prototype: SymbolInfo;
+    } & TypeInfoCommon)
+  | ({ type: 'unknown' } & TypeInfoCommon)
+  | ({ type: 'any' } & TypeInfoCommon)
+  | ({
+      type: 'misc';
+    } & TypeInfoCommon);
+
+export type SymbolInfo = {
+  name: string;
+  jsDoc?: {
+    description?: string;
+    jsDocTags: Array<{ name: string; text?: string }>;
+  };
+  typeInfo: TypeInfo;
+  tsMetadata: {
+    symbol: ts.Symbol;
+    type: ts.Type;
+    symbolFlags: Array<keyof typeof ts.SymbolFlags>;
+  };
+};

package/src/utils.ts

@@ -0,0 +1,61 @@
+import { TypeInfo } from './types.js';
+
+/**
+ * Extracts all set enum flags from a given value.
+ *
+ * @returns An array of enum keys (names) that are set in the given flags value
+ *
+ * @example
+ * enum Permissions {
+ *   Read = 1,
+ *   Write = 2,
+ *   Execute = 4
+ * }
+ * const flags = Permissions.Read | Permissions.Write;
+ * const setFlags = getSetFlags({ flags, enumObject: Permissions });
+ * console.log(setFlags); // Output: ["Read", "Write"]
+ */
+export function getSetFlags<T extends Record<string, unknown>>({
+  flags,
+  enumObject,
+}: {
+  /**
+   * The flags value to check
+   */
+  flags: number;
+  /**
+   * The enum object to check against
+   */
+  enumObject: T;
+}): Array<keyof T> {
+  /**
+   * HEADS UP: this uses "bitwise" which is not well understood
+   * So if you see `&` and think it should be `&&` you're wrong
+   * Crazy stuff goes on
+   * In TypeScript, enums are represented as numbers, for example see `ts.SymbolFlags` or `ts.TypeFlags`
+   * In a `symbol.flags` it is a `number` that is created from multiple numbers each representing a flag.
+   * This function is used to extract the flags from the number.
+   * @see https://patrickdesjardins.com/blog/how-to-set-and-read-bitwise-enum-values-in-typescript
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_AND
+   */
+  return (Object.entries(enumObject) as Array<[keyof T, number]>)
+    .filter(([, value]) => {
+      // Only consider power of 2 values (single flags)
+      // eslint-disable-next-line no-bitwise
+      if ((value & (value - 1)) !== 0) return false;
+      // Check if the flag is set
+      // eslint-disable-next-line no-bitwise
+      return (flags & value) !== 0;
+    })
+    .map(([key]) => key);
+}
+
+export function assertTypeInfo<T extends TypeInfo['type']>(
+  typeInfo: TypeInfo,
+  type: T,
+): asserts typeInfo is Extract<TypeInfo, { type: T }> {
+  if (typeInfo.type !== type) {
+    const msg = `Expected type to be "${type}", got "${typeInfo.type}"`;
+    throw new Error(msg);
+  }
+}

package/src/utils.vtest.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import ts from 'typescript';
+import { getSetFlags } from './utils.js';
+
+describe('utils tests', () => {
+  it('getSetFlags single flag', () => {
+    const single = getSetFlags({
+      enumObject: ts.SymbolFlags,
+      flags: ts.SymbolFlags.Property,
+    });
+    expect(single).toEqual(['Property'] satisfies typeof single);
+  });
+
+  it('getSetFlags multiple flags', () => {
+    const multiple = getSetFlags({
+      enumObject: ts.SymbolFlags,
+      flags:
+        // eslint-disable-next-line no-bitwise
+        ts.SymbolFlags.FunctionScopedVariable |
+        ts.SymbolFlags.BlockScopedVariable,
+    });
+    expect(multiple).toEqual([
+      'FunctionScopedVariable',
+      'BlockScopedVariable',
+    ] satisfies typeof multiple);
+  });
+
+  it('single flag with multiple flags extracted', () => {
+    // an "Accessor" is both a "GetAccessor" and a "SetAccessor"
+    const single = getSetFlags({
+      enumObject: ts.SymbolFlags,
+      flags: ts.SymbolFlags.Accessor,
+    });
+    expect(single).toEqual([
+      'GetAccessor',
+      'SetAccessor',
+    ] satisfies typeof single);
+  });
+});