@latticexyz/cli 1.40.0 → 1.41.1-alpha.0

package/src/config/loadStoreConfig.ts

@@ -1,95 +1,13 @@
-import { SchemaType, getStaticByteLength } from "@latticexyz/schema-type";
-import { z, ZodError } from "zod";
+import { ZodError } from "zod";
 import { fromZodErrorCustom } from "../utils/errors.js";
-import { BaseRoute, ObjectName, OrdinaryRoute, ValueName } from "./commonSchemas.js";
 import { loadConfig } from "./loadConfig.js";
-
-const TableName = ObjectName;
-const KeyName = ValueName;
-const ColumnName = ValueName;
-
-const PrimaryKey = z
-  .nativeEnum(SchemaType)
-  .refine((arg) => getStaticByteLength(arg) > 0, "Primary key must not use dynamic SchemaType");
-const PrimaryKeys = z.record(KeyName, PrimaryKey).default({ key: SchemaType.BYTES32 });
-
-const Schema = z
-  .record(ColumnName, z.nativeEnum(SchemaType))
-  .refine((arg) => Object.keys(arg).length > 0, "Table schema may not be empty");
-
-const FullTable = z
-  .object({
-    route: OrdinaryRoute.default("/tables"),
-    tableIdArgument: z.boolean().default(false),
-    storeArgument: z.boolean().default(false),
-    primaryKeys: PrimaryKeys,
-    schema: Schema,
-    dataStruct: z.boolean().optional(),
-  })
-  .transform((arg) => {
-    // default dataStruct value depends on schema's length
-    if (Object.keys(arg.schema).length === 1) {
-      arg.dataStruct ??= false;
-    } else {
-      arg.dataStruct ??= true;
-    }
-    return arg as Omit<typeof arg, "dataStruct"> & Required<Pick<typeof arg, "dataStruct">>;
-  });
-
-const DefaultSingleValueTable = z.nativeEnum(SchemaType).transform((schemaType) => {
-  return FullTable.parse({
-    schema: {
-      value: schemaType,
-    },
-  });
-});
-
-export const StoreConfig = z.object({
-  baseRoute: BaseRoute.default(""),
-  storeImportPath: z.string().default("@latticexyz/store/src/"),
-  tables: z.record(TableName, z.union([DefaultSingleValueTable, FullTable])),
-});
-
-// zod doesn't preserve doc comments
-export interface StoreUserConfig {
-  /** The base route prefix for table ids. Default is "" (empty string) */
-  baseRoute?: string;
-  /** Path for store package imports. Default is "@latticexyz/store/src/" */
-  storeImportPath?: string;
-  /**
-   * Configuration for each table.
-   *
-   * The key is the table name (capitalized).
-   *
-   * The value:
-   *  - SchemaType for a single-value table (aka ECS component).
-   *  - FullTableConfig object for multi-value tables (or for customizable options).
-   */
-  tables: Record<string, SchemaType | FullTableConfig>;
-}
-
-interface FullTableConfig {
-  /** Output path for the file, and relevant for the table id. The table id will be keccak256(concat(baseRoute,route,tableName)). Default is "tables/" */
-  route?: string;
-  /** Make methods accept `tableId` argument instead of it being a hardcoded constant. Default is false */
-  tableIdArgument?: boolean;
-  /** Include methods that accept a manual `IStore` argument. Default is false. */
-  storeArgument?: boolean;
-  /** Include a data struct and methods for it. Default is false for 1-column tables; true for multi-column tables. */
-  dataStruct?: boolean;
-  /** Table's primary key names mapped to their types. Default is `{ key: SchemaType.BYTES32 }` */
-  primaryKeys?: Record<string, SchemaType>;
-  /** Table's column names mapped to their types. Table name's 1st letter should be lowercase. */
-  schema: Record<string, SchemaType>;
-}
-
-export type StoreConfig = z.output<typeof StoreConfig>;
+import { parseStoreConfig } from "./parseStoreConfig.js";
 
 export async function loadStoreConfig(configPath?: string) {
   const config = await loadConfig(configPath);
 
   try {
-    return parseStoreConfig(config);
+    return parseStoreConfig(config as any);
   } catch (error) {
     if (error instanceof ZodError) {
       throw fromZodErrorCustom(error, "StoreConfig Validation Error");
@@ -98,7 +16,3 @@ export async function loadStoreConfig(configPath?: string) {
     }
   }
 }
-
-export async function parseStoreConfig(config: unknown) {
-  return StoreConfig.parse(config);
-}

package/src/config/parseStoreConfig.test-d.ts

@@ -0,0 +1,40 @@
+import { describe, expectTypeOf } from "vitest";
+import { z } from "zod";
+import { storeConfig, zStoreConfig, StoreUserConfig } from "./parseStoreConfig.js";
+
+describe("StoreUserConfig", () => {
+  // Typecheck manual interfaces against zod
+  expectTypeOf<StoreUserConfig>().toEqualTypeOf<z.input<typeof zStoreConfig>>();
+  // type equality isn't deep for optionals
+  expectTypeOf<StoreUserConfig["tables"][string]>().toEqualTypeOf<z.input<typeof zStoreConfig>["tables"][string]>();
+  expectTypeOf<NonNullable<StoreUserConfig["enums"]>[string]>().toEqualTypeOf<
+    NonNullable<NonNullable<z.input<typeof zStoreConfig>>["enums"]>[string]
+  >();
+  // TODO If more nested schemas are added, provide separate tests for them
+
+  // Test possible inference confusion.
+  // This would fail if you remove `AsDependent` from `StoreUserConfig`
+  expectTypeOf(
+    storeConfig({
+      tables: {
+        Table1: {
+          primaryKeys: {
+            a: "Enum1",
+          },
+          schema: {
+            b: "Enum2",
+          },
+        },
+        Table2: {
+          schema: {
+            a: "uint32",
+          },
+        },
+      },
+      enums: {
+        Enum1: ["E1"],
+        Enum2: ["E1"],
+      },
+    })
+  ).toEqualTypeOf<StoreUserConfig<"Enum1" | "Enum2", "Enum1" | "Enum2">>();
+});

package/src/config/parseStoreConfig.ts

@@ -0,0 +1,314 @@
+import { AbiType, AbiTypes, StaticAbiType, StaticAbiTypes } from "@latticexyz/schema-type";
+import { RefinementCtx, z, ZodIssueCode } from "zod";
+import { AsDependent, ExtractUserTypes, RequireKeys, StaticArray, StringForUnion } from "../utils/typeUtils.js";
+import { zObjectName, zSelector, zUserEnum, zValueName } from "./commonSchemas.js";
+import { getDuplicates, parseStaticArray } from "./validation.js";
+
+const zTableName = zObjectName;
+const zKeyName = zValueName;
+const zColumnName = zValueName;
+const zUserEnumName = zObjectName;
+
+// Fields can use AbiType or one of user-defined wrapper types
+// (user types are refined later, based on the appropriate config options)
+const zFieldData = z.string();
+
+type FieldData<UserTypes extends StringForUnion> = AbiType | StaticArray | UserTypes;
+
+// Primary keys allow only static types
+// (user types are refined later, based on the appropriate config options)
+const zPrimaryKey = z.string();
+const zPrimaryKeys = z.record(zKeyName, zPrimaryKey).default({ key: "bytes32" });
+
+type PrimaryKey<StaticUserTypes extends StringForUnion> = StaticAbiType | StaticUserTypes;
+
+/************************************************************************
+ *
+ *    TABLE SCHEMA
+ *
+ ************************************************************************/
+
+export type FullSchemaConfig<UserTypes extends StringForUnion = StringForUnion> = Record<string, FieldData<UserTypes>>;
+export type ShorthandSchemaConfig<UserTypes extends StringForUnion = StringForUnion> = FieldData<UserTypes>;
+export type SchemaConfig<UserTypes extends StringForUnion = StringForUnion> =
+  | FullSchemaConfig<UserTypes>
+  | ShorthandSchemaConfig<UserTypes>;
+
+const zFullSchemaConfig = z
+  .record(zColumnName, zFieldData)
+  .refine((arg) => Object.keys(arg).length > 0, "Table schema may not be empty");
+
+const zShorthandSchemaConfig = zFieldData.transform((fieldData) => {
+  return zFullSchemaConfig.parse({
+    value: fieldData,
+  });
+});
+
+export const zSchemaConfig = zFullSchemaConfig.or(zShorthandSchemaConfig);
+
+/************************************************************************
+ *
+ *    TABLE
+ *
+ ************************************************************************/
+
+export interface TableConfig<
+  UserTypes extends StringForUnion = StringForUnion,
+  StaticUserTypes extends StringForUnion = StringForUnion
+> {
+  /** Output directory path for the file. Default is "tables" */
+  directory?: string;
+  /**
+   * The fileSelector is used with the namespace to register the table and construct its id.
+   * The table id will be uint256(bytes32(abi.encodePacked(bytes16(namespace), bytes16(fileSelector)))).
+   * Default is "<tableName>"
+   * */
+  fileSelector?: string;
+  /** Make methods accept `tableId` argument instead of it being a hardcoded constant. Default is false */
+  tableIdArgument?: boolean;
+  /** Include methods that accept a manual `IStore` argument. Default is false. */
+  storeArgument?: boolean;
+  /** Include a data struct and methods for it. Default is false for 1-column tables; true for multi-column tables. */
+  dataStruct?: boolean;
+  /** Table's primary key names mapped to their types. Default is `{ key: "bytes32" }` */
+  primaryKeys?: Record<string, PrimaryKey<StaticUserTypes>>;
+  /** Table's column names mapped to their types. Table name's 1st letter should be lowercase. */
+  schema: SchemaConfig<UserTypes>;
+}
+
+const zFullTableConfig = z
+  .object({
+    directory: z.string().default("tables"),
+    fileSelector: zSelector.optional(),
+    tableIdArgument: z.boolean().default(false),
+    storeArgument: z.boolean().default(false),
+    primaryKeys: zPrimaryKeys,
+    schema: zSchemaConfig,
+    dataStruct: z.boolean().optional(),
+  })
+  .transform((arg) => {
+    // default dataStruct value depends on schema's length
+    if (Object.keys(arg.schema).length === 1) {
+      arg.dataStruct ??= false;
+    } else {
+      arg.dataStruct ??= true;
+    }
+    return arg as RequireKeys<typeof arg, "dataStruct">;
+  });
+
+const zShorthandTableConfig = zFieldData.transform((fieldData) => {
+  return zFullTableConfig.parse({
+    schema: {
+      value: fieldData,
+    },
+  });
+});
+
+export const zTableConfig = zFullTableConfig.or(zShorthandTableConfig);
+
+/************************************************************************
+ *
+ *    TABLES
+ *
+ ************************************************************************/
+
+export type TablesConfig<
+  UserTypes extends StringForUnion = StringForUnion,
+  StaticUserTypes extends StringForUnion = StringForUnion
+> = Record<string, TableConfig<UserTypes, StaticUserTypes> | FieldData<UserTypes>>;
+
+export const zTablesConfig = z.record(zTableName, zTableConfig).transform((tables) => {
+  // default fileSelector depends on tableName
+  for (const tableName of Object.keys(tables)) {
+    const table = tables[tableName];
+    table.fileSelector ??= tableName;
+
+    tables[tableName] = table;
+  }
+  return tables as Record<string, RequireKeys<(typeof tables)[string], "fileSelector">>;
+});
+
+/************************************************************************
+ *
+ *    USER TYPES
+ *
+ ************************************************************************/
+
+export type EnumsConfig<EnumNames extends StringForUnion> = never extends EnumNames
+  ? {
+      /**
+       * Enum names mapped to lists of their member names
+       *
+       * (enums are inferred to be absent)
+       */
+      enums?: Record<EnumNames, string[]>;
+    }
+  : StringForUnion extends EnumNames
+  ? {
+      /**
+       * Enum names mapped to lists of their member names
+       *
+       * (enums aren't inferred - use `mudConfig` or `storeConfig` helper, and `as const` for variables)
+       */
+      enums?: Record<EnumNames, string[]>;
+    }
+  : {
+      /**
+       * Enum names mapped to lists of their member names
+       *
+       * Enums defined here can be used as types in table schemas/keys
+       */
+      enums: Record<EnumNames, string[]>;
+    };
+
+export const zEnumsConfig = z.object({
+  enums: z.record(zUserEnumName, zUserEnum).default({}),
+});
+
+/************************************************************************
+ *
+ *    FINAL
+ *
+ ************************************************************************/
+
+// zod doesn't preserve doc comments
+export type StoreUserConfig<
+  EnumNames extends StringForUnion = StringForUnion,
+  StaticUserTypes extends ExtractUserTypes<EnumNames> = ExtractUserTypes<EnumNames>
+> = EnumsConfig<EnumNames> & {
+  /** The namespace for table ids. Default is "" (empty string) */
+  namespace?: string;
+  /** Path for store package imports. Default is "@latticexyz/store/src/" */
+  storeImportPath?: string;
+  /**
+   * Configuration for each table.
+   *
+   * The key is the table name (capitalized).
+   *
+   * The value:
+   *  - abi or user type for a single-value table.
+   *  - FullTableConfig object for multi-value tables (or for customizable options).
+   */
+  tables: TablesConfig<AsDependent<StaticUserTypes>, AsDependent<StaticUserTypes>>;
+  /** Path to the file where common user types will be generated and imported from. Default is "Types" */
+  userTypesPath?: string;
+};
+
+/** Type helper for defining StoreUserConfig */
+export function storeConfig<
+  // (`never` is overridden by inference, so only the defined enums can be used by default)
+  EnumNames extends StringForUnion = never,
+  StaticUserTypes extends ExtractUserTypes<EnumNames> = ExtractUserTypes<EnumNames>
+>(config: StoreUserConfig<EnumNames, StaticUserTypes>) {
+  return config;
+}
+
+export type StoreConfig = z.output<typeof zStoreConfig>;
+
+const StoreConfigUnrefined = z
+  .object({
+    namespace: zSelector.default(""),
+    storeImportPath: z.string().default("@latticexyz/store/src/"),
+    tables: zTablesConfig,
+    userTypesPath: z.string().default("Types"),
+  })
+  .merge(zEnumsConfig);
+
+// finally validate global conditions
+export const zStoreConfig = StoreConfigUnrefined.superRefine(validateStoreConfig);
+
+export function parseStoreConfig(config: unknown) {
+  return zStoreConfig.parse(config);
+}
+
+/************************************************************************
+ *
+ *    HELPERS
+ *
+ ************************************************************************/
+
+// Validate conditions that check multiple different config options simultaneously
+function validateStoreConfig(config: z.output<typeof StoreConfigUnrefined>, ctx: RefinementCtx) {
+  // Local table variables must be unique within the table
+  for (const table of Object.values(config.tables)) {
+    const primaryKeyNames = Object.keys(table.primaryKeys);
+    const fieldNames = Object.keys(table.schema);
+    const duplicateVariableNames = getDuplicates([...primaryKeyNames, ...fieldNames]);
+    if (duplicateVariableNames.length > 0) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `Field and primary key names within one table must be unique: ${duplicateVariableNames.join(", ")}`,
+      });
+    }
+  }
+  // Global names must be unique
+  const tableNames = Object.keys(config.tables);
+  const staticUserTypeNames = Object.keys(config.enums);
+  const userTypeNames = staticUserTypeNames;
+  const globalNames = [...tableNames, ...userTypeNames];
+  const duplicateGlobalNames = getDuplicates(globalNames);
+  if (duplicateGlobalNames.length > 0) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Table, enum names must be globally unique: ${duplicateGlobalNames.join(", ")}`,
+    });
+  }
+  // User types must exist
+  for (const table of Object.values(config.tables)) {
+    for (const primaryKeyType of Object.values(table.primaryKeys)) {
+      validateStaticAbiOrUserType(staticUserTypeNames, primaryKeyType, ctx);
+    }
+    for (const fieldType of Object.values(table.schema)) {
+      validateAbiOrUserType(userTypeNames, staticUserTypeNames, fieldType, ctx);
+    }
+  }
+}
+
+function validateAbiOrUserType(
+  userTypeNames: string[],
+  staticUserTypeNames: string[],
+  type: string,
+  ctx: RefinementCtx
+) {
+  if (!(AbiTypes as string[]).includes(type) && !userTypeNames.includes(type)) {
+    const staticArray = parseStaticArray(type);
+    if (staticArray) {
+      validateStaticArray(staticUserTypeNames, staticArray.elementType, staticArray.staticLength, ctx);
+    } else {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `${type} is not a valid abi type, and is not defined in userTypes`,
+      });
+    }
+  }
+}
+
+function validateStaticAbiOrUserType(staticUserTypeNames: string[], type: string, ctx: RefinementCtx) {
+  if (!(StaticAbiTypes as string[]).includes(type) && !staticUserTypeNames.includes(type)) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `${type} is not a static type`,
+    });
+  }
+}
+
+function validateStaticArray(
+  staticUserTypeNames: string[],
+  elementType: string,
+  staticLength: number,
+  ctx: RefinementCtx
+) {
+  validateStaticAbiOrUserType(staticUserTypeNames, elementType, ctx);
+
+  if (staticLength === 0) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Static array length must not be 0`,
+    });
+  } else if (staticLength >= 2 ** 16) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Static array length must be less than 2**16`,
+    });
+  }
+}

package/src/config/validation.ts

@@ -1,3 +1,4 @@
+import { ethers } from "ethers";
 import { ZodIssueCode, RefinementCtx } from "zod";
 
 export function validateName(name: string, ctx: RefinementCtx) {
@@ -31,6 +32,30 @@ export function validateUncapitalizedName(name: string, ctx: RefinementCtx) {
   }
 }
 
+// validates only the enum array, not the names of enum members
+export function validateEnum(members: string[], ctx: RefinementCtx) {
+  if (members.length === 0) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Enum must not be empty`,
+    });
+  }
+  if (members.length >= 256) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Length of enum must be < 256`,
+    });
+  }
+
+  const duplicates = getDuplicates(members);
+  if (duplicates.length > 0) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Enum must not have duplicate names for: ${duplicates.join(", ")}`,
+    });
+  }
+}
+
 function _factoryForValidateRoute(requireNonEmpty: boolean, requireSingleLevel: boolean) {
   return (route: string, ctx: RefinementCtx) => {
     if (route === "") {
@@ -90,3 +115,49 @@ export const validateRoute = _factoryForValidateRoute(true, false);
 export const validateBaseRoute = _factoryForValidateRoute(false, false);
 
 export const validateSingleLevelRoute = _factoryForValidateRoute(true, true);
+
+export function validateEthereumAddress(address: string, ctx: RefinementCtx) {
+  if (!ethers.utils.isAddress(address)) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Address must be a valid Ethereum address`,
+    });
+  }
+}
+
+export function getDuplicates<T>(array: T[]) {
+  const checked = new Set<T>();
+  const duplicates = new Set<T>();
+  for (const element of array) {
+    if (checked.has(element)) {
+      duplicates.add(element);
+    }
+    checked.add(element);
+  }
+  return [...duplicates];
+}
+
+export function validateSelector(name: string, ctx: RefinementCtx) {
+  if (name.length > 16) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Selector must be <= 16 characters`,
+    });
+  }
+  if (!/^\w*$/.test(name)) {
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: `Selector must contain only alphanumeric & underscore characters`,
+    });
+  }
+}
+
+/** Returns null if the type does not look like a static array, otherwise element and length data */
+export function parseStaticArray(abiType: string) {
+  const matches = abiType.match(/^(\w+)\[(\d+)\]$/);
+  if (!matches) return null;
+  return {
+    elementType: matches[1],
+    staticLength: Number.parseInt(matches[2]),
+  };
+}

package/src/config/world/index.ts

@@ -0,0 +1,4 @@
+export * from "./loadWorldConfig.js";
+export * from "./parseWorldConfig.js";
+export * from "./resolveWorldConfig.js";
+export * from "./userTypes.js";

package/src/config/world/loadWorldConfig.test-d.ts

@@ -0,0 +1,11 @@
+import { describe, expectTypeOf } from "vitest";
+import { z } from "zod";
+import { zWorldConfig, WorldUserConfig } from "./index.js";
+
+describe("loadWorldConfig", () => {
+  // Typecheck manual interfaces against zod
+  expectTypeOf<WorldUserConfig>().toEqualTypeOf<z.input<typeof zWorldConfig>>();
+  // type equality isn't deep for optionals
+  expectTypeOf<WorldUserConfig["overrideSystems"]>().toEqualTypeOf<z.input<typeof zWorldConfig>["overrideSystems"]>();
+  // TODO If more nested schemas are added, provide separate tests for them
+});

package/src/config/world/loadWorldConfig.ts

@@ -0,0 +1,26 @@
+import { ZodError } from "zod";
+import { fromZodErrorCustom } from "../../utils/errors.js";
+import { loadConfig } from "../loadConfig.js";
+import { zWorldConfig } from "./parseWorldConfig.js";
+import { resolveWorldConfig } from "./resolveWorldConfig.js";
+
+/**
+ * Loads and resolves the world config.
+ * @param configPath Path to load the config from. Defaults to "mud.config.mts" or "mud.config.ts"
+ * @param existingContracts Optional list of existing contract names to validate system names against. If not provided, no validation is performed. Contract names ending in `System` will be added to the config with default values.
+ * @returns Promise of ResolvedWorldConfig object
+ */
+export async function loadWorldConfig(configPath?: string, existingContracts?: string[]) {
+  const config = await loadConfig(configPath);
+
+  try {
+    const parsedConfig = zWorldConfig.parse(config);
+    return resolveWorldConfig(parsedConfig, existingContracts);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw fromZodErrorCustom(error, "WorldConfig Validation Error");
+    } else {
+      throw error;
+    }
+  }
+}

package/src/config/world/parseWorldConfig.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { zEthereumAddress, zObjectName, zSelector } from "../commonSchemas.js";
+import { DynamicResolutionType } from "../dynamicResolution.js";
+
+const zSystemName = zObjectName;
+const zModuleName = zObjectName;
+const zSystemAccessList = z.array(zSystemName.or(zEthereumAddress)).default([]);
+
+// The system config is a combination of a fileSelector config and access config
+const zSystemConfig = z.intersection(
+  z.object({
+    fileSelector: zSelector,
+    registerFunctionSelectors: z.boolean().default(true),
+  }),
+  z.discriminatedUnion("openAccess", [
+    z.object({
+      openAccess: z.literal(true),
+    }),
+    z.object({
+      openAccess: z.literal(false),
+      accessList: zSystemAccessList,
+    }),
+  ])
+);
+
+const zValueWithType = z.object({
+  value: z.union([z.string(), z.number(), z.instanceof(Uint8Array)]),
+  type: z.string(),
+});
+const zDynamicResolution = z.object({ type: z.nativeEnum(DynamicResolutionType), input: z.string() });
+
+const zModuleConfig = z.object({
+  name: zModuleName,
+  root: z.boolean().default(false),
+  args: z.array(z.union([zValueWithType, zDynamicResolution])).default([]),
+});
+
+// The parsed world config is the result of parsing the user config
+export const zWorldConfig = z.object({
+  namespace: zSelector.default(""),
+  worldContractName: z.string().optional(),
+  overrideSystems: z.record(zSystemName, zSystemConfig).default({}),
+  excludeSystems: z.array(zSystemName).default([]),
+  postDeployScript: z.string().default("PostDeploy"),
+  deploysDirectory: z.string().default("./deploys"),
+  worldgenDirectory: z.string().default("world"),
+  worldImportPath: z.string().default("@latticexyz/world/src/"),
+  modules: z.array(zModuleConfig).default([]),
+});
+
+export async function parseWorldConfig(config: unknown) {
+  return zWorldConfig.parse(config);
+}
+
+export type ParsedWorldConfig = z.output<typeof zWorldConfig>;