@rbxts/diff 1.0.1 → 1.0.2

package/out/index.d.ts

@@ -1,3 +1,4 @@
+type GenericRecord = Record<string | number, unknown>;
 type Primitive = string | number | boolean | undefined;
 type Length<T> = T extends {
     length: infer N extends number;
@@ -17,6 +18,41 @@ export interface Diff<T> {
     readonly changed?: DeepPartial<T>;
     readonly removed?: DeepKeys<T>;
 }
-export declare function createDiff<T extends {}>(oldData: T, newData: T): Diff<T>;
+export interface DiffOptions<K> {
+    readonly equals?: (a: unknown, b: unknown) => boolean;
+    readonly ignoreKeys?: K[];
+}
+/**
+ * Creates a diff object by comparing two data structures.
+ *
+ * @param oldData - The original data object
+ * @param newData - The new data object to compare against
+ * @param options - Configuration options for diff generation
+ * @param options.equals - Custom equality function for comparing values (default: `===`)
+ * @param options.ignoreKeys - Array of keys to exclude from diff comparison (shallow, root level only)
+ * @returns A Diff object containing changed and removed keys, or an empty object if no differences
+ *
+ * @example
+ * const diff = createDiff(
+ *   { a: 1, b: 2 },
+ *   { a: 1, b: 3, c: 4 }
+ * );
+ * // Returns: { changed: { b: 3, c: 4 } }
+ */
+export declare function createDiff<T extends {}>(oldData: T, newData: T, { equals, ignoreKeys }?: DiffOptions<T extends GenericRecord ? keyof T : unknown>): Diff<T>;
+/**
+ * Applies a diff to a base object and returns the modified result.
+ *
+ * @param base - The base object to apply the diff to
+ * @param diff - The diff object containing changes and removals
+ * @returns A new object with the diff applied to the base
+ *
+ * @example
+ * const result = applyDiff(
+ *   { a: 1, b: 2, c: 3 },
+ *   { changed: { b: 5 }, removed: { c: true } }
+ * );
+ * // Returns: { a: 1, b: 5 }
+ */
 export declare function applyDiff<T extends {}>(base: T, diff: Diff<T>): T;
 export {};

package/out/init.luau

@@ -1,8 +1,52 @@
 -- Compiled with roblox-ts v3.0.0
-local function createDiff(oldData, newData)
+local function isEmpty(record)
+	for _element, _element_1 in pairs(record) do
+		local _ = { _element, _element_1 }
+		return false
+	end
+	return true
+end
+--[[
+	*
+	 * Creates a diff object by comparing two data structures.
+	 *
+	 * @param oldData - The original data object
+	 * @param newData - The new data object to compare against
+	 * @param options - Configuration options for diff generation
+	 * @param options.equals - Custom equality function for comparing values (default: `===`)
+	 * @param options.ignoreKeys - Array of keys to exclude from diff comparison (shallow, root level only)
+	 * @returns A Diff object containing changed and removed keys, or an empty object if no differences
+	 *
+	 * @example
+	 * const diff = createDiff(
+	 *   { a: 1, b: 2 },
+	 *   { a: 1, b: 3, c: 4 }
+	 * );
+	 * // Returns: { changed: { b: 3, c: 4 } }
+	 
+]]
+local function createDiff(oldData, newData, _param)
+	if _param == nil then
+		_param = {}
+	end
+	local equals = _param.equals
+	if equals == nil then
+		equals = function(a, b)
+			return a == b
+		end
+	end
+	local ignoreKeys = _param.ignoreKeys
+	if ignoreKeys == nil then
+		ignoreKeys = {}
+	end
 	if oldData == newData then
 		return {}
 	end
+	local _set = {}
+	for _, _v in ignoreKeys do
+		_set[_v] = true
+	end
+	local keyIgnoreSet = _set
 	local _oldData = oldData
 	local _arg0 = type(_oldData) == "table"
 	assert(_arg0, "attempt to create diff of non-table objects")
@@ -11,45 +55,58 @@ local function createDiff(oldData, newData)
 	assert(_arg0_1, "attempt to create diff of non-table objects")
 	local changed = {}
 	local removed = {}
-	for key in pairs(oldData) do
+	for key in oldData do
+		if keyIgnoreSet[key] ~= nil then
+			continue
+		end
 		if newData[key] ~= nil then
 			continue
 		end
 		removed[key] = true
 	end
-	for key, newValue in pairs(newData) do
-		local oldValue = oldData[key]
-		if oldValue == nil then
-			changed[key] = newValue
+	for key, newValue in newData do
+		if keyIgnoreSet[key] ~= nil then
 			continue
 		end
-		if (not (type(oldValue) == "table") or not (type(newValue) == "table")) and oldValue ~= newValue then
-			changed[key] = newValue
+		local oldValue = oldData[key]
+		if type(oldValue) == "table" and type(newValue) == "table" then
+			local childDiff = createDiff(oldValue, newValue, {
+				equals = equals,
+			})
+			if childDiff.changed ~= nil then
+				changed[key] = childDiff.changed
+			end
+			if childDiff.removed ~= nil then
+				removed[key] = childDiff.removed
+			end
 			continue
 		end
-		local childDiff = createDiff(oldValue, newValue)
-		if childDiff.changed ~= nil then
-			changed[key] = childDiff.changed or newValue
-		end
-		if childDiff.removed ~= nil then
-			removed[key] = childDiff.removed
+		if equals(oldValue, newValue) then
+			continue
 		end
-	end
-	local changedCount = 0
-	local removedCount = 0
-	for _element, _element_1 in pairs(changed) do
-		local _ = { _element, _element_1 }
-		changedCount += 1
-	end
-	for _element, _element_1 in pairs(removed) do
-		local _ = { _element, _element_1 }
-		removedCount += 1
+		changed[key] = newValue
 	end
 	return {
-		changed = if changedCount > 0 then changed else nil,
-		removed = if removedCount > 0 then removed else nil,
+		changed = if isEmpty(changed) then nil else changed,
+		removed = if isEmpty(removed) then nil else removed,
 	}
 end
+--[[
+	*
+	 * Applies a diff to a base object and returns the modified result.
+	 *
+	 * @param base - The base object to apply the diff to
+	 * @param diff - The diff object containing changes and removals
+	 * @returns A new object with the diff applied to the base
+	 *
+	 * @example
+	 * const result = applyDiff(
+	 *   { a: 1, b: 2, c: 3 },
+	 *   { changed: { b: 5 }, removed: { c: true } }
+	 * );
+	 * // Returns: { a: 1, b: 5 }
+	 
+]]
 local function applyDiff(base, diff)
 	local _base = base
 	local _arg0 = type(_base) == "table"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/diff",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Calculate diffs between objects and apply diffs to objects",
   "author": "runicly",
   "main": "out/init.lua",