@superblocksteam/util 2.0.162 → 2.0.163-next.0

package/src/resource-configs.ts

@@ -1,356 +0,0 @@
-import path from "path";
-
-import fs from "fs-extra";
-
-import {
-  DEV_ENVIRONMENT_CONFIG_PATH,
-  RESOURCE_CONFIG_PATH,
-} from "./constants.js";
-
-type SuperblocksMetadata = {
-  cliVersion: string;
-};
-
-// Resource type is the type of the resource in the Superblocks platform
-export type SuperblocksResourceType = "APPLICATION" | "BACKEND";
-
-// Resource-specific config
-export type SuperblocksConfigType =
-  | "APPLICATION"
-  | "APPLICATION_V2"
-  | "BACKEND";
-
-export type VersionedResourceConfig = {
-  location: string;
-  resourceType: SuperblocksResourceType;
-};
-
-export type SuperblocksResourceConfigMetadata = {
-  fileVersion?: string;
-};
-
-export type SuperblocksResourceConfig = {
-  id: string;
-  configType: SuperblocksConfigType;
-  metadata?: SuperblocksResourceConfigMetadata;
-};
-
-export type SuperblocksBackendConfig = SuperblocksResourceConfig &
-  SourceFilesContanier & {
-    configType: "BACKEND";
-  };
-
-export type SuperblocksApplicationConfig = SuperblocksResourceConfig & {
-  configType: "APPLICATION";
-  defaultPageId?: string;
-  // @deprecated use pageApis appApis for new format
-  apis?: Record<string, string>; // used for pre-0.2.0 format
-  appApis?: Record<string, ApiInfo>; // used for 0.2.0+ format
-  pages?: Record<string, PageInfo>;
-};
-
-export type PageInfo = {
-  id: string;
-  name: string;
-  // @deprecated use pageApis instead
-  apis?: Record<string, string>; // used for pre-0.2.0 format
-  pageApis?: Record<string, ApiInfo>; // used for 0.2.0+ format
-};
-
-type SourceFilesContanier = {
-  sourceFiles?: string[];
-};
-
-export type ApiInfo = SourceFilesContanier & {
-  name: string;
-};
-
-export type SuperblocksApplicationV2Config = SuperblocksResourceConfig & {
-  configType: "APPLICATION_V2";
-};
-
-export type SuperblocksMonorepoConfig = {
-  configType: "ROOT";
-  resources: Record<string, VersionedResourceConfig>;
-  metadata: SuperblocksMetadata;
-};
-
-export type SuperblocksConfig =
-  | SuperblocksMonorepoConfig
-  | SuperblocksApplicationConfig
-  | SuperblocksApplicationV2Config
-  | SuperblocksBackendConfig;
-
-type DevEnvironmentConfigType = "DEV_ENVIRONMENT";
-
-export type SuperblocksDevEnvironmentConfig = {
-  configType: DevEnvironmentConfigType;
-  branch?: string;
-};
-
-/**
- * Get the Superblocks dev environment config file from the current directory (and optionally) hierarchy
- * @param checkParentDir Whether to recursively check the parent directory for a Superblocks dev environment config file
- * @param pathPrefix The path prefix to use for the search
- * @returns The Superblocks dev environment config and the path to the config file
- */
-export async function getSuperblocksDevEnvironmentConfigJson(
-  checkParentDir = false,
-  pathPrefix = "",
-): Promise<[SuperblocksDevEnvironmentConfig, string]> {
-  const absolutePath = path.resolve(pathPrefix);
-
-  let hasReachedFilesystemRoot = false;
-  try {
-    hasReachedFilesystemRoot = path.parse(absolutePath).root == absolutePath;
-  } catch {
-    throw new Error("Could not parse path " + absolutePath);
-  }
-
-  if (
-    (pathPrefix && !fs.existsSync(absolutePath)) ||
-    hasReachedFilesystemRoot
-  ) {
-    throw new Error(
-      "No Superblocks config file found in current directory hierarchy " +
-        pathPrefix,
-    );
-  }
-
-  const attemptedPath = path.join(absolutePath, DEV_ENVIRONMENT_CONFIG_PATH);
-  try {
-    const devEnvironmentConfig = await fs.readJSON(attemptedPath);
-    if (devEnvironmentConfig.configType !== "DEV_ENVIRONMENT") {
-      throw new Error("Not the dev environment Superblocks config file");
-    }
-    return [
-      devEnvironmentConfig as SuperblocksDevEnvironmentConfig,
-      attemptedPath,
-    ];
-  } catch {
-    if (!checkParentDir) {
-      // no superblocks config file found
-      throw new Error(
-        "No Superblocks config file found in current directory " +
-          attemptedPath,
-      );
-    }
-    return getSuperblocksDevEnvironmentConfigJson(true, "../" + pathPrefix);
-  }
-}
-
-/**
- * Get the Superblocks config file from the current directory (and optionally) hierarchy
- * @param checkParentDir Whether to recursively check the parent directory for a Superblocks config file
- */
-export async function getSuperblocksMonorepoConfigJson(
-  checkParentDir = false,
-  pathPrefix = "",
-): Promise<[SuperblocksMonorepoConfig, string]> {
-  const absolutePath = path.resolve(pathPrefix);
-
-  let hasReachedFilesystemRoot = false;
-  try {
-    hasReachedFilesystemRoot = path.parse(absolutePath).root == absolutePath;
-  } catch {
-    throw new Error("Could not parse path " + absolutePath);
-  }
-
-  let superblocksConfig;
-  if (
-    (pathPrefix && !fs.existsSync(absolutePath)) ||
-    hasReachedFilesystemRoot
-  ) {
-    throw new Error(
-      "No Superblocks config file found in current directory hierarchy " +
-        pathPrefix,
-    );
-  }
-
-  const attemptedPath = path.join(absolutePath, RESOURCE_CONFIG_PATH);
-  try {
-    superblocksConfig = await fs.readJSON(attemptedPath);
-    if (superblocksConfig.configType !== "ROOT") {
-      throw new Error("Not the root Superblocks config file");
-    }
-    return [superblocksConfig as SuperblocksMonorepoConfig, attemptedPath];
-  } catch {
-    if (!checkParentDir) {
-      // no superblocks config file found
-      throw new Error(
-        "No Superblocks config file found in current directory " +
-          attemptedPath,
-      );
-    }
-    return getSuperblocksMonorepoConfigJson(true, "../" + pathPrefix);
-  }
-}
-
-export async function getSuperblocksApplicationConfigJson(
-  applicationPath?: string,
-): Promise<SuperblocksApplicationConfig> {
-  let superblocksConfig;
-  try {
-    const configPath = applicationPath
-      ? path.join(applicationPath, RESOURCE_CONFIG_PATH)
-      : RESOURCE_CONFIG_PATH;
-    superblocksConfig = await fs.readJSON(configPath);
-  } catch {
-    // no superblocks config file found
-    throw new Error(
-      "This command must be run within a Superblocks app directory.",
-    );
-  }
-
-  if (superblocksConfig.configType !== "APPLICATION") {
-    throw new Error(
-      "Please execute this command within a Superblocks application directory.",
-    );
-  }
-
-  return superblocksConfig as SuperblocksApplicationConfig;
-}
-
-export async function getSuperblocksApplicationConfigIfExists(
-  applicationPath: string,
-): Promise<SuperblocksApplicationConfig | undefined> {
-  let superblocksConfig: SuperblocksApplicationConfig | undefined;
-  try {
-    const configPath = applicationPath
-      ? path.join(applicationPath, RESOURCE_CONFIG_PATH)
-      : RESOURCE_CONFIG_PATH;
-    superblocksConfig = await fs.readJSON(configPath);
-  } catch {
-    // no superblocks config file found
-  }
-
-  if (superblocksConfig?.configType !== "APPLICATION") {
-    return undefined;
-  }
-
-  return superblocksConfig as SuperblocksApplicationConfig;
-}
-
-export async function getSuperblocksApplicationV2ConfigJson(
-  applicationPath?: string,
-): Promise<SuperblocksApplicationV2Config> {
-  let superblocksConfig;
-  try {
-    const configPath = applicationPath
-      ? path.join(applicationPath, RESOURCE_CONFIG_PATH)
-      : RESOURCE_CONFIG_PATH;
-    superblocksConfig = await fs.readJSON(configPath);
-  } catch {
-    // no superblocks config file found
-    throw new Error(
-      "This command must be run within a Superblocks app directory.",
-    );
-  }
-
-  if (superblocksConfig.configType !== "APPLICATION_V2") {
-    throw new Error(
-      "Please execute this command within a Superblocks application directory.",
-    );
-  }
-
-  return superblocksConfig as SuperblocksApplicationV2Config;
-}
-
-export async function getSuperblocksBackendConfigIfExists(
-  backendPath: string,
-): Promise<SuperblocksBackendConfig | undefined> {
-  let superblocksConfig: SuperblocksBackendConfig | undefined;
-  try {
-    const configPath = backendPath
-      ? path.join(backendPath, RESOURCE_CONFIG_PATH)
-      : RESOURCE_CONFIG_PATH;
-    superblocksConfig = await fs.readJSON(configPath);
-  } catch {
-    // no superblocks config file found
-  }
-
-  if (superblocksConfig?.configType !== "BACKEND") {
-    return undefined;
-  }
-
-  return superblocksConfig as SuperblocksBackendConfig;
-}
-
-async function getSuperblocksBackendConfigJson(): Promise<SuperblocksBackendConfig> {
-  let superblocksConfig;
-  try {
-    superblocksConfig = await fs.readJSON(RESOURCE_CONFIG_PATH);
-  } catch {
-    // no superblocks config file found
-    throw new Error(
-      "This command must be run within a Superblocks backend resource (workflow/job) directory.",
-    );
-  }
-
-  if (superblocksConfig.configType !== "BACKEND") {
-    throw new Error(
-      "Please execute this command within a Superblocks backend resource (workflow/job) directory.",
-    );
-  }
-
-  return superblocksConfig as SuperblocksBackendConfig;
-}
-
-export async function getSuperblocksResourceConfigIfExists(): Promise<
-  SuperblocksResourceConfig | undefined
-> {
-  let config: SuperblocksResourceConfig | undefined;
-  try {
-    config = await getSuperblocksApplicationConfigJson();
-  } catch {
-    // Noop
-  }
-  try {
-    config = await getSuperblocksApplicationV2ConfigJson();
-  } catch {
-    // Noop
-  }
-  try {
-    config = await getSuperblocksBackendConfigJson();
-  } catch {
-    // Noop
-  }
-  return config;
-}
-
-export function getResourceIdFromUrl(
-  resourceUrl: any,
-): [string, SuperblocksResourceType] {
-  const url = new URL(resourceUrl);
-  if (url.pathname.startsWith("/code-mode")) {
-    // find the first uuid in the url
-    const tokens = url.pathname.split("/");
-    const uuid = tokens.find((token) =>
-      token.match(
-        /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
-      ),
-    );
-    if (!uuid) {
-      throw new Error(`Failed to parse resource URL: ${resourceUrl}`);
-    }
-    return [uuid, "APPLICATION"];
-  }
-  if (url.pathname.startsWith("/applications")) {
-    const tokens = url.pathname.split("/");
-    if (tokens.length < 2) {
-      throw new Error(`Failed to parse resource URL: ${resourceUrl}`);
-    }
-    if (tokens[2] === "edit") {
-      return [tokens[3], "APPLICATION"];
-    } else {
-      return [tokens[2], "APPLICATION"];
-    }
-  } else if (
-    url.pathname.startsWith("/workflows") ||
-    url.pathname.startsWith("/scheduled_jobs")
-  ) {
-    return [url.pathname.split("/")[2], "BACKEND"];
-  }
-
-  throw new Error(`Failed to parse resource URL: ${resourceUrl}`);
-}

package/src/token-manager.ts

@@ -1,26 +0,0 @@
-import type { EventEmitter } from "node:events";
-
-export interface TokenUpdateEvent {
-  token: string;
-}
-
-export interface ITokenManager extends EventEmitter {
-  updateToken(newToken: string): void;
-  /**
-   * Returns the most recently set token, or `undefined` if `updateToken`
-   * has never been called. Consumers that need to seed themselves at
-   * construction time read this synchronously rather than waiting on the
-   * next `tokenUpdated` event — the event stream stays as the refresh
-   * channel and is not replayed for late subscribers.
-   *
-   * Closes the cold-start gap where a listener attached after a prior
-   * emission would observe nothing (Node `EventEmitter` has no replay).
-   */
-  getCurrentToken(): string | undefined;
-  on(event: "tokenUpdated", listener: (event: TokenUpdateEvent) => void): this;
-  once(
-    event: "tokenUpdated",
-    listener: (event: TokenUpdateEvent) => void,
-  ): this;
-  off(event: "tokenUpdated", listener: (event: TokenUpdateEvent) => void): this;
-}

package/src/types.ts

@@ -1,138 +0,0 @@
-import type { UUID } from "node:crypto";
-
-import type { DataType } from "./data-types.js";
-
-interface PropertiesPanelDisplay<T extends DataType> {
-  /**
-   * Determines what form item type is shown in the Superblocks properties panel.
-   *
-   * Only booleans are allowed to use the "switch" control
-   */
-  controlType: T extends "boolean"
-    ? "text" | "js-expr" | "switch"
-    : "text" | "js-expr";
-
-  /**
-   * Determines form item label in the Superblocks properties panel.
-   */
-  label: string;
-
-  /**
-   * Placeholder text appears as gray text in the properties panel. This only applies
-   * to text-like inputs.
-   */
-  placeholder?: string;
-
-  /**
-   * This shows up in the popover as a user types into the properties panel.
-   * This is a documentation field that helps users understand what type of data is accepted
-   * by this property. You should give a specific example, not a generic type
-   *
-   * @example {
-   *   label: "My Label",
-   *   value: "myValue"
-   * }
-   */
-  exampleData?: string;
-
-  /**
-   * This shows up in the popover as a user types into the properties panel.
-   * This is a documentation field that helps users understand what type of data is accepted
-   * by this property. Typescript notation is recommended.
-   *
-   * @example "Array<{ label: string; value: string; }>"
-   */
-  expectedType?: string;
-
-  /**
-   * The default value should match the dataType of the property.
-   */
-  defaultValue?: T;
-
-  /**
-   * The default value to use when adding a property.
-   */
-  defaultOnAdd?: T;
-}
-
-interface PropertyForData<T extends DataType> {
-  path: string;
-  dataType: T;
-
-  /**
-   * The presence of this object determines whether or not this property
-   * shows up in the Superblocks properties panel.
-   **/
-  propertiesPanelDisplay?: PropertiesPanelDisplay<T>;
-
-  /**
-   * A description of this property. This is used in the Superblocks properties panel
-   * as well as in the custom component's autocomplete.
-   **/
-  description?: string;
-
-  /**
-   * By default, all your properties are readable from anywhere in Superblocks using dot notation
-   * (e.g. `myComponent.myProperty`). If you want to hide a property from the outside world,
-   * set this to true
-   * @default false
-   */
-  isExternallyReadable?: boolean;
-
-  /**
-   * By default, all properties can have be used with Set Component Property and Reset Component to Default.
-   * @default true
-   **/
-  isExternallySettable?: boolean;
-}
-
-export type Property =
-  | PropertyForData<"string">
-  | PropertyForData<"number">
-  | PropertyForData<"boolean">
-  | PropertyForData<"any">;
-
-export interface ComponentConfig {
-  id: UUID;
-
-  /**
-   * @example: "myComponent"
-   */
-  name: string;
-
-  /**
-   * @example "My Component"
-   */
-  displayName: string;
-
-  /**
-   * @example "components/myComponent/component.tsx"
-   */
-  componentPath: string;
-
-  properties: Array<
-    // Note to devs: The reason we are duplicating the Property type above is that it produces a better
-    // error message. The user will see 'is not assignable to type PropertyForData<"string"> | PropertyForData<"number">'
-    // instead of seeing "is not assignable to type Property"
-    | PropertyForData<"string">
-    | PropertyForData<"number">
-    | PropertyForData<"boolean">
-    | PropertyForData<"any">
-  >;
-
-  /**
-   * @example [{
-   *  label: "On Click",
-   *  path: "onClick",
-   * }]
-   */
-  events: Array<{
-    label: string;
-    path: string;
-  }>;
-
-  gridDimensions?: {
-    initialColumns: number;
-    initialRows: number;
-  };
-}

package/src/unreachable.ts

@@ -1,5 +0,0 @@
-export function unreachable(value: never, errMsg?: string): never {
-  throw new TypeError(
-    errMsg ?? "Encountered impossible value: " + JSON.stringify(value),
-  );
-}

package/src/validation.ts

@@ -1,155 +0,0 @@
-import Ajv from "ajv";
-import type { Schema } from "ajv";
-import type { DataValidateFunction } from "ajv/dist/types";
-import betterAjvErrors from "better-ajv-errors";
-
-import { isReservedPropertyName, isValidIdentifier } from "./identifiers.js";
-
-const ajv = new Ajv();
-
-ajv.addKeyword({
-  keyword: "stringFormat",
-  compile: (schema: any) => {
-    let validateFunc: DataValidateFunction;
-    // schema is the value assigned to stringFormat in the schema
-    if (schema === "identifier") {
-      validateFunc = (data: any) => {
-        if (typeof data != "string") return false;
-        if (!isValidIdentifier(data)) {
-          validateFunc.errors = [
-            {
-              keyword: "format",
-              message:
-                "must be a valid identifier starting with a-z or underscore and containing only a-z, 0-9, and underscores",
-            },
-          ];
-          return false;
-        }
-        if (isReservedPropertyName(data)) {
-          validateFunc.errors = [
-            {
-              keyword: "format",
-              message: "must not match a reserved property path",
-            },
-          ];
-          return false;
-        }
-        return true;
-      };
-    } else {
-      throw new Error(`Unknown stringFormat: ${schema}`);
-    }
-    return validateFunc;
-  },
-  errors: true,
-});
-
-const componentSchema: Schema = {
-  type: "object",
-  properties: {
-    id: { type: "string" },
-    name: { type: "string" },
-    displayName: { type: "string" },
-    componentPath: { type: "string" },
-    properties: {
-      type: "array",
-      items: {
-        $ref: "#/definitions/Property",
-      },
-    },
-    events: {
-      type: "array",
-      items: {
-        $ref: "#/definitions/EventHandler",
-      },
-    },
-    gridDimensions: {
-      type: "object",
-      properties: {
-        initialColumns: { type: "number" },
-        initialRows: { type: "number" },
-      },
-      additionalProperties: false,
-      required: ["initialColumns", "initialRows"],
-    },
-  },
-  required: [
-    "id",
-    "name",
-    "displayName",
-    "componentPath",
-    "properties",
-    "events",
-  ],
-  additionalProperties: false,
-  definitions: {
-    Property: {
-      properties: {
-        path: { $ref: "#/definitions/Identifier" },
-        dataType: { enum: ["number", "boolean", "string", "any"] },
-        propertiesPanelDisplay: {
-          type: "object",
-          properties: {
-            label: { type: "string" },
-            controlType: { enum: ["text", "js-expr", "switch"] },
-            defaultValue: {
-              oneOf: [
-                {
-                  type: "string",
-                },
-                {
-                  type: "boolean",
-                },
-                {
-                  type: "number",
-                },
-              ],
-            },
-            placeholder: { type: "string" },
-            exampleData: { type: "string" },
-            expectedType: { type: "string" },
-          },
-          required: ["controlType", "label"],
-          additionalProperties: false,
-        },
-        description: { type: "string" },
-        isExternallySettable: { type: "boolean" },
-        isExternallyReadable: { type: "boolean" },
-      },
-      type: "object",
-      additionalProperties: false,
-      required: ["path", "dataType"],
-    },
-    EventHandler: {
-      properties: {
-        label: { type: "string" },
-        path: { $ref: "#/definitions/Identifier" },
-      },
-      type: "object",
-      additionalProperties: false,
-      required: ["label", "path"],
-    },
-    Identifier: {
-      type: "string",
-      stringFormat: "identifier",
-    },
-  },
-};
-
-const validate = ajv.compile(componentSchema);
-
-export function validateCustomComponents(data: any): {
-  valid: boolean;
-  message?: string;
-} {
-  const valid = validate(data);
-  if (!valid) {
-    return {
-      valid: false,
-      message: betterAjvErrors(componentSchema, data, validate.errors as any, {
-        indent: 2,
-      }),
-    };
-  }
-  return { valid: true };
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "declaration": true,
-    "module": "nodenext",
-    "moduleDetection": "force",
-    "moduleResolution": "nodenext",
-    "isolatedModules": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "composite": true,
-    "target": "es2024",
-    "lib": ["es2024", "ESNext.Array", "ESNext.Collection", "ESNext.Promise"],
-
-    "sourceMap": true,
-    "declarationMap": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  },
-  "include": ["src/**/*"]
-}