Merge pull request #394 from dojoengine/feat/migration1.1

feat: create migration guide to update to v1.1

migration/v1-0-v1-1.md

@@ -0,0 +1,196 @@
+# Dojo.js Migration Guide - Query System Changes
+
+## Major Changes Overview
+
+- Default query system now uses `ToriiQueryBuilder` instead of the legacy `QueryBuilder`
+- Schema is no longer required as a parameter when initializing the SDK
+- Subscription APIs now return initial data along with the subscription
+- The `getEntities` and `getEventMessages` APIs have been simplified
+- Cartridge connector has been removed from the example
+
+## Initialization Changes
+
+### Before
+
+```typescript
+const sdk = await init<SchemaType>(
+    {
+        client: {
+            rpcUrl: getRpcUrl(),
+            toriiUrl: env.VITE_TORII_URL,
+            // ...
+        },
+        domain: {
+            /* ... */
+        },
+    },
+    schema
+);
+```
+
+### After
+
+```typescript
+const sdk = await init<SchemaType>({
+    client: {
+        rpcUrl: getRpcUrl(),
+        toriiUrl: env.VITE_TORII_URL,
+        // ...
+    },
+    domain: {
+        /* ... */
+    },
+});
+```
+
+## Query System Changes
+
+### Entity Queries
+
+#### Before
+
+```typescript
+const query = new QueryBuilder<SchemaType>()
+    .namespace("onchain_dash", (n) =>
+        n.entity("CallerCounter", (e) =>
+            e.eq("caller", addAddressPadding(address))
+        )
+    )
+    .build();
+```
+
+#### After
+
+```typescript
+const query = new ToriiQueryBuilder()
+    .withClause(
+        KeysClause(
+            ["onchain_dash-CallerCounter"],
+            [addAddressPadding(address)],
+            "FixedLen"
+        ).build()
+    )
+    .includeHashedKeys();
+```
+
+## Subscription API Changes
+
+### Before
+
+```typescript
+const sub = await sdk.subscribeEntityQuery({
+    query: query,
+    callback: ({ data, error }) => {
+        // Handle updates
+    },
+});
+```
+
+### After
+
+```typescript
+const [initialEntities, sub] = await sdk.subscribeEntityQuery({
+    query: query,
+    callback: ({ data, error }) => {
+        // Handle updates
+    },
+});
+
+// initialEntities contains the first query result
+// sub is the subscription for future updates
+```
+
+## Entity Query Examples
+
+### Querying Single Entity
+
+```typescript
+// New way using ToriiQueryBuilder
+const query = new ToriiQueryBuilder()
+    // Model has only `key` in his models key
+    .withClause(KeysClause(["namespace-Model"], [key], "FixedLen").build())
+    .includeHashedKeys();
+```
+
+### Querying Multiple Entities
+
+```typescript
+const query = new ToriiQueryBuilder()
+    .withClause(
+        KeysClause(
+            ["namespace-Model1", "namespace-Model2"],
+            [key],
+            // Model has at least `key` in his models keys
+            "VariableLen"
+        ).build()
+    )
+    .includeHashedKeys();
+```
+
+## Important Notes
+
+1. **Query Builder Migration**
+
+    - The legacy `QueryBuilder` is now deprecated
+    - Use `ToriiQueryBuilder` with `KeysClause` for better performance
+    - Always call `.includeHashedKeys()` when using subscriptions to retrieve Torii internal entity ids
+
+2. **Subscription Handling**
+
+    - Subscriptions now return a tuple: `[initialData, subscription]`
+    - Handle initial data immediately instead of making a separate query
+    - Use the subscription for subsequent updates
+
+3. **Key Types**
+
+    - `FixedLen`: Use when querying exact key matches
+    - `VariableLen`: Use when querying multiple entities or partial key matches
+
+4. **Breaking Changes**
+    - Simplified API surface for entity queries
+    - Changed return types for subscription methods
+
+## Performance Considerations
+
+- The new query system is more efficient for large-scale applications
+- Subscription initial data is returned immediately, reducing network requests
+- Key-based queries provide better performance than complex filters
+
+## Common Migration Patterns
+
+### Converting Complex Queries
+
+```typescript
+// Old way
+const query = new QueryBuilder()
+    .namespace("game", (n) =>
+        n.entity("Player", (e) => e.eq("status", "active"))
+    )
+    .build();
+
+// New way
+const query = new ToriiQueryBuilder()
+    .withClause(KeysClause(["game-Player"], [status], "FixedLen").build())
+    .includeHashedKeys();
+```
+
+### Handling Multiple Entities
+
+```typescript
+// New way to handle multiple entity types
+const query = new ToriiQueryBuilder()
+    .withClause(
+        KeysClause(
+            [ModelsMapping.Entity1, ModelsMapping.Entity2],
+            [commonKey],
+            "VariableLen"
+        ).build()
+    )
+    .includeHashedKeys();
+```
+
+## Additional Resources
+
+- Check the official Dojo documentation for more details
+- Review the example applications in the repository
+- Join the Dojo Discord for migration support