feat(common): clarify resourceId (hex) from resource (object) (#1706)

.changeset/thirty-cups-provide.md

@@ -0,0 +1,19 @@
+---
+"@latticexyz/common": minor
+---
+
+Renames `resourceIdToHex` to `resourceToHex` and `hexToResourceId` to `hexToResource`, to better distinguish between a resource ID (hex value) and a resource reference (type, namespace, name).
+
+```diff
+- resourceIdToHex({ type: 'table', namespace: '', name: 'Position' });
++ resourceToHex({ type: 'table', namespace: '', name: 'Position' });
+```
+
+```diff
+- hexToResourceId('0x...');
++ hexToResource('0x...');
+```
+
+Previous methods still exist but are now deprecated to ease migration and reduce breaking changes. These will be removed in a future version.
+
+Also removes the previously deprecated and unused table ID utils (replaced by these resource ID utils).

.changeset/wild-squids-bathe.md

@@ -0,0 +1,7 @@
+---
+"@latticexyz/cli": patch
+"@latticexyz/dev-tools": patch
+"@latticexyz/store-sync": patch
+---
+
+Moved to new resource ID utils.

e2e/packages/sync-test/data/setContractData.ts

@@ -2,7 +2,7 @@ import { Page } from "@playwright/test";
 import { Data } from "./types";
 import { encodeTestData } from "./encodeTestData";
 import { callWorld } from "./callWorld";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 
 /**
  * Writes contract data by calling `world.setRecord` via the client
@@ -14,7 +14,7 @@ export async function setContractData(page: Page, data: Data) {
     for (const record of records) {
       const promise = await callWorld(page, "setRecord", [
         // TODO: add support for multiple namespaces after https://github.com/latticexyz/mud/issues/994 is resolved
-        resourceIdToHex({ type: "table", namespace: "", name: table }),
+        resourceToHex({ type: "table", namespace: "", name: table }),
         record.key,
         record.staticData,
         record.encodedLengths,

packages/cli/src/commands/trace.ts

@@ -9,12 +9,12 @@ import { StoreConfig } from "@latticexyz/store";
 import { resolveWorldConfig, WorldConfig } from "@latticexyz/world";
 import IBaseWorldAbi from "@latticexyz/world/out/IBaseWorld.sol/IBaseWorld.abi.json" assert { type: "json" };
 import worldConfig from "@latticexyz/world/mud.config.js";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 import { getExistingContracts } from "../utils/getExistingContracts";
 import { getChainId } from "../utils/utils/getChainId";
 
 // TODO account for multiple namespaces (https://github.com/latticexyz/mud/issues/994)
-const systemsTableId = resourceIdToHex({
+const systemsTableId = resourceToHex({
   type: "system",
   namespace: worldConfig.namespace,
   name: worldConfig.tables.Systems.name,
@@ -80,7 +80,7 @@ const commandModule: CommandModule<Options, Options> = {
     const systemTableFieldLayout = await WorldContract.getFieldLayout(systemsTableId);
     const labels: { name: string; address: string }[] = [];
     for (const name of names) {
-      const systemSelector = resourceIdToHex({ type: "system", namespace, name });
+      const systemSelector = resourceToHex({ type: "system", namespace, name });
       // Get the first field of `Systems` table (the table maps system name to its address and other data)
       const address = await WorldContract.getField(systemsTableId, [systemSelector], 0, systemTableFieldLayout);
       labels.push({ name, address });

packages/cli/src/utils/deploy.ts

@@ -22,7 +22,7 @@ import { getContractData } from "./utils/getContractData";
 import { postDeploy } from "./utils/postDeploy";
 import { setInternalFeePerGas } from "./utils/setInternalFeePerGas";
 import { ContractCode } from "./utils/types";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 
 export interface DeployConfig {
   profile?: string;
@@ -151,7 +151,7 @@ export async function deploy(
       nonce: nonce++,
       contract: worldContract,
       func: "registerNamespace",
-      args: [resourceIdToHex({ type: "namespace", namespace: mudConfig.namespace, name: "" })],
+      args: [resourceToHex({ type: "namespace", namespace: mudConfig.namespace, name: "" })],
     });
     console.log(chalk.green("Namespace registered"));
   }

packages/cli/src/utils/systems/getGrantAccessCallData.ts

@@ -1,6 +1,6 @@
 import { System } from "./types";
 import { CallData } from "../utils/types";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 
 export async function getGrantAccessCallData(input: {
   systems: System[];
@@ -24,6 +24,6 @@ export async function getGrantAccessCallData(input: {
 function getGrantSystemAccessCallData(name: string, namespace: string, address: string): CallData {
   return {
     func: "grantAccess",
-    args: [resourceIdToHex({ type: "system", namespace, name }), address],
+    args: [resourceToHex({ type: "system", namespace, name }), address],
   };
 }

packages/cli/src/utils/systems/getRegisterFunctionSelectorsCallData.ts

@@ -1,4 +1,4 @@
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 import { System } from "./types";
 import { loadFunctionSignatures, toFunctionSelector } from "./utils";
 import { CallData } from "../utils/types";
@@ -46,12 +46,12 @@ function getRegisterFunctionSelectorCallData(input: {
     const functionSelector = toFunctionSelector(systemFunctionSignature);
     return {
       func: "registerRootFunctionSelector",
-      args: [resourceIdToHex({ type: "system", namespace, name }), systemFunctionSignature, functionSelector],
+      args: [resourceToHex({ type: "system", namespace, name }), systemFunctionSignature, functionSelector],
     };
   } else {
     return {
       func: "registerFunctionSelector",
-      args: [resourceIdToHex({ type: "system", namespace, name }), systemFunctionSignature],
+      args: [resourceToHex({ type: "system", namespace, name }), systemFunctionSignature],
     };
   }
 }

packages/cli/src/utils/systems/getRegisterSystemCallData.ts

@@ -1,4 +1,4 @@
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 import { System } from "./types";
 import { CallData } from "../utils/types";
 
@@ -12,6 +12,6 @@ export async function getRegisterSystemCallData(input: {
   const systemAddress = await systemContracts[systemKey];
   return {
     func: "registerSystem",
-    args: [resourceIdToHex({ type: "system", namespace, name: system.name }), systemAddress, system.openAccess],
+    args: [resourceToHex({ type: "system", namespace, name: system.name }), systemAddress, system.openAccess],
   };
 }

packages/cli/src/utils/tables/getRegisterTableCallData.ts

@@ -1,7 +1,7 @@
 import { encodeSchema, getStaticByteLength } from "@latticexyz/schema-type/deprecated";
 import { StoreConfig } from "@latticexyz/store";
 import { resolveAbiOrUserType } from "@latticexyz/store/codegen";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 import { Table } from "./types";
 import { fieldLayoutToHex } from "@latticexyz/protocol-parser";
 import { CallData } from "../utils/types";
@@ -38,7 +38,7 @@ export function getRegisterTableCallData(
     func: "registerTable",
     args: [
       // TODO: add support for table namespaces (https://github.com/latticexyz/mud/issues/994)
-      resourceIdToHex({ type: table.offchainOnly ? "offchainTable" : "table", namespace: storeConfig.namespace, name }),
+      resourceToHex({ type: table.offchainOnly ? "offchainTable" : "table", namespace: storeConfig.namespace, name }),
       fieldLayoutToHex(fieldLayout),
       encodeSchema(keyTypes),
       encodeSchema(schemaTypes),

packages/cli/src/utils/tables/getTableIds.ts

@@ -1,13 +1,13 @@
 import { StoreConfig } from "@latticexyz/store";
 import { TableIds } from "./types";
-import { resourceIdToHex } from "@latticexyz/common";
+import { resourceToHex } from "@latticexyz/common";
 import { hexToBytes } from "viem";
 
 export function getTableIds(storeConfig: StoreConfig): TableIds {
   const tableIds: TableIds = {};
   for (const [tableName, { name, offchainOnly }] of Object.entries(storeConfig.tables)) {
     tableIds[tableName] = hexToBytes(
-      resourceIdToHex({
+      resourceToHex({
         type: offchainOnly ? "offchainTable" : "table",
         namespace: storeConfig.namespace,
         name,

packages/common/package.json

@@ -13,7 +13,6 @@
     ".": "./dist/index.js",
     "./chains": "./dist/chains.js",
     "./codegen": "./dist/codegen.js",
-    "./deprecated": "./dist/deprecated.js",
     "./errors": "./dist/errors.js",
     "./foundry": "./dist/foundry.js",
     "./type-utils": "./dist/type-utils.js",
@@ -30,9 +29,6 @@
       "codegen": [
         "./src/codegen/index.ts"
       ],
-      "deprecated": [
-        "./src/deprecated/index.ts"
-      ],
       "errors": [
         "./src/errors/index.ts"
       ],

packages/common/src/common.ts

@@ -1,7 +1,9 @@
+import { Hex } from "viem";
 import { ResourceType } from "./resourceTypes";
 
-export type ResourceId = {
+export type Resource = {
+  resourceId: Hex;
+  type: ResourceType;
   namespace: string;
   name: string;
-  type: ResourceType;
 };

packages/common/src/createContract.ts → packages/common/src/deprecated/createContract.ts

@@ -1,4 +1,4 @@
-import { getContract } from "./getContract";
+import { getContract } from "../getContract";
 
 /** @deprecated use `getContract` instead */
 export const createContract = getContract;

packages/common/src/deprecated/hexToResourceId.ts

@@ -0,0 +1,4 @@
+import { hexToResource } from "../hexToResource";
+
+/** @deprecated use `hexToResource` instead */
+export const hexToResourceId = hexToResource;

packages/common/src/deprecated/resourceIdToHex.ts

@@ -0,0 +1,4 @@
+import { resourceToHex } from "../resourceToHex";
+
+/** @deprecated use `resourceToHex` instead */
+export const resourceIdToHex = resourceToHex;

packages/common/src/hexToResource.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { hexToResource } from "./hexToResource";
+
+describe("hexToResource", () => {
+  it("can convert from hex string", () => {
+    const resource = hexToResource("0x74626e616d65737061636500000000006e616d65000000000000000000000000");
+    expect(resource.type).toMatchInlineSnapshot('"table"');
+    expect(resource.namespace).toMatchInlineSnapshot('"namespace"');
+    expect(resource.name).toMatchInlineSnapshot('"name"');
+  });
+});

packages/common/src/hexToResourceId.ts → packages/common/src/hexToResource.ts

@@ -1,7 +1,7 @@
 import { Hex, hexToString, sliceHex } from "viem";
-import { ResourceId } from "./common";
+import { Resource } from "./common";
 import { ResourceType, resourceTypes } from "./resourceTypes";
-import { resourceTypeIds } from "./resourceIdToHex";
+import { resourceTypeIds } from "./resourceToHex";
 import { ReverseMap } from "./type-utils/common";
 
 const resourceTypeIdToType = Object.fromEntries(
@@ -16,7 +16,7 @@ function getResourceType(resourceTypeId: string): ResourceType | undefined {
   }
 }
 
-export function hexToResourceId(hex: Hex): ResourceId {
+export function hexToResource(hex: Hex): Resource {
   const resourceTypeId = hexToString(sliceHex(hex, 0, 2)).replace(/\0+$/, "");
   const type = getResourceType(resourceTypeId);
   const namespace = hexToString(sliceHex(hex, 2, 16)).replace(/\0+$/, "");
@@ -26,5 +26,5 @@ export function hexToResourceId(hex: Hex): ResourceId {
     throw new Error(`Unknown resource type: ${resourceTypeId}`);
   }
 
-  return { type, namespace, name };
+  return { resourceId: hex, type, namespace, name };
 }

packages/common/src/index.ts

@@ -5,13 +5,17 @@ export * from "./getContract";
 export * from "./getBurnerPrivateKey";
 export * from "./getNonceManager";
 export * from "./getNonceManagerId";
-export * from "./hexToResourceId";
+export * from "./hexToResource";
 export * from "./readHex";
-export * from "./resourceIdToHex";
+export * from "./resourceToHex";
 export * from "./resourceTypes";
 export * from "./spliceHex";
 export * from "./transportObserver";
 export * from "./writeContract";
 
 /** @deprecated use `getContract` instead */
-export { createContract } from "./createContract";
+export { createContract } from "./deprecated/createContract";
+/** @deprecated use `resourceToHex` instead */
+export { resourceIdToHex } from "./deprecated/resourceIdToHex";
+/** @deprecated use `hexToResource` instead */
+export { hexToResourceId } from "./deprecated/hexToResourceId";