lexshift 0.0.1

package/README.md

@@ -0,0 +1,47 @@
+# lexshift
+
+`lexshift` helps you work with evolving AT Protocol lexicons by identifying record revisions and shifting records to a target revision.
+
+It is designed for schema evolution workflows where records need to remain usable across multiple lexicon versions.
+
+## Installation
+
+```bash
+npm install lexshift
+```
+
+## API overview
+
+- `identify(record, options?)`: Detects which lexicon revision a record matches.
+- `shift(record, targetRevision, options?)`: Migrates a record to a requested revision.
+
+Both functions support a `historyProvider` option so you can supply historical lexicons when the current revision does not match.
+
+## Example
+
+```ts
+import { identify, shift } from "lexshift";
+
+const record = {
+  $type: "com.example.profile",
+  name: "Ada",
+};
+
+const historyProvider = async ({ nsid, current }) => {
+  const previousLexicons = await fetchHistorySomehow(nsid, current.revision);
+  return previousLexicons.map((candidate) => ({
+    revision: candidate.revision,
+    lexicon: candidate.lexicon,
+    cid: candidate.cid,
+  }));
+};
+
+const identified = await identify(record, { historyProvider });
+
+const migrated = await shift(record, 3, { historyProvider });
+```
+
+## Notes
+
+- `record.$type` must contain a valid NSID.
+- If no matching revision is found, the functions throw an error.

package/dist/index.d.mts

@@ -0,0 +1,96 @@
+import { LexResolver } from "@atproto/lex-resolver";
+import { LexRecord, LexiconDoc } from "@atproto/lexicon";
+
+//#region src/types.d.ts
+/**
+ * An ATproto record containing a `$type` value.
+ */
+interface ATProtoRecord extends Record<string, unknown> {
+  $type: string;
+}
+interface RevisionedATProtoRecord<R extends ATProtoRecord> {
+  revision: number;
+  record: R;
+}
+interface RevisionedATProtoRecordWithHistory<R extends ATProtoRecord> extends RevisionedATProtoRecord<R> {
+  lexicons: Array<LexiconHistoryCandidate>;
+}
+interface ResolvedLexicon {
+  revision: number;
+  lexicon: LexiconDoc;
+  cid: string;
+  did: string;
+  uri: string;
+}
+interface LexiconHistoryCandidate {
+  revision?: number;
+  lexicon: unknown;
+  cid?: string;
+}
+/**
+ * An ATproto record along with its NSID and current lexicon revision. This data
+ * should be used to fetch previous lexicons.
+ */
+interface IdentifyHistoryProviderInput<R extends ATProtoRecord> {
+  nsid: string;
+  record: R;
+  current: ResolvedLexicon;
+}
+type IdentifyHistoryProvider<R extends ATProtoRecord> = (input: IdentifyHistoryProviderInput<R>) => Iterable<LexiconHistoryCandidate> | AsyncIterable<LexiconHistoryCandidate> | Promise<Iterable<LexiconHistoryCandidate> | AsyncIterable<LexiconHistoryCandidate>>;
+interface LexshiftOptions<R extends ATProtoRecord> {
+  /**
+   * A function that takes in a given input and returns a list of lexicon history candidates.
+   */
+  historyProvider?: IdentifyHistoryProvider<R>;
+  /**
+   * A function to resolve a lexicon document from the AT protocol network.
+   */
+  resolver?: LexResolver;
+}
+interface KeyDifferences {
+  unchanged: Array<string>;
+  converted: Array<[string, LexRecordProperty, LexRecordProperty]>;
+  renamed: Array<[string, string]>;
+  dropped: Array<string>;
+  created: Array<[string, unknown]>;
+}
+type LexRecordProperty = LexRecord["record"]["properties"][string];
+//#endregion
+//#region src/identify.d.ts
+interface IdentifyOptions<R extends ATProtoRecord, ReturnLexicons extends boolean = false> extends LexshiftOptions<R> {
+  /**
+   * Whether the lexicons for the record should be returned as well.
+   */
+  returnLexicons?: ReturnLexicons;
+}
+/**
+ * Identifies the lexicon revision for a given record by analyzing it's keys.
+ *
+ * First, this function attempts to fetch the current lexicon, verifies it, and matches the record against it.
+ * In a case where the record matches, it will return this revision of the lexicon.
+ *
+ * Should the record not match the lexicon and if there is an older revision, that older revision will be retreived.
+ * This happens until the first revision of the lexicon is reached, at which point the record either matches,
+ * or the function throws an error because it does not.
+ *
+ * @param record The record to get the revision for.
+ * @param options Options for resolving the lexicon, including historical data.
+ */
+declare function identify<R extends ATProtoRecord>(record: R, options: IdentifyOptions<R, true>): Promise<RevisionedATProtoRecordWithHistory<R>>;
+declare function identify<R extends ATProtoRecord>(record: R, options?: IdentifyOptions<R, false>): Promise<RevisionedATProtoRecord<R>>;
+//#endregion
+//#region src/shift.d.ts
+/**
+ * Shifts a record from its current lexicon revision to another one, by either upshifting or downshifting.
+ *
+ * @param record The record to shift.
+ * @param newRevision The revision to shift to.
+ * @param options The options for this function.
+ */
+declare function shift<R extends ATProtoRecord, N extends number, S extends ATProtoRecord>(record: R, newRevision: N, options?: LexshiftOptions<R>): Promise<{
+  oldRevision: number;
+  newRevision: N;
+  record: S;
+}>;
+//#endregion
+export { ATProtoRecord, IdentifyHistoryProvider, IdentifyHistoryProviderInput, KeyDifferences, LexRecordProperty, LexiconHistoryCandidate, LexshiftOptions, ResolvedLexicon, RevisionedATProtoRecord, RevisionedATProtoRecordWithHistory, identify, shift };

package/dist/index.mjs

@@ -0,0 +1,471 @@
+import { LexResolver } from "@atproto/lex-resolver";
+import { BlobRef, Lexicons, ValidationError, parseLexiconDoc } from "@atproto/lexicon";
+//#region src/identify.ts
+async function identify(record, options = {}) {
+	const normalizedNsid = record.$type.trim();
+	if (normalizedNsid.length === 0) throw new Error("NSID is required");
+	const currentResult = await (options.resolver ?? new LexResolver({})).get(normalizedNsid);
+	const currentLexicon = parseLexiconDoc(structuredClone(currentResult.lexicon));
+	if (currentLexicon.id !== normalizedNsid) throw new Error(`Resolved lexicon id ${currentLexicon.id} does not match requested NSID ${normalizedNsid}`);
+	const resolvedCurrent = {
+		revision: currentLexicon.revision ?? 1,
+		lexicon: currentLexicon,
+		cid: currentResult.cid.toString(),
+		did: currentResult.uri.host,
+		uri: currentResult.uri.toString()
+	};
+	const history = options.historyProvider ? await Array.fromAsync(await options.historyProvider({
+		nsid: normalizedNsid,
+		record,
+		current: resolvedCurrent
+	})) : void 0;
+	if (matchesLexicon(record, normalizedNsid, resolvedCurrent.lexicon)) {
+		if (options.returnLexicons === true) return {
+			revision: resolvedCurrent.revision,
+			record,
+			lexicons: history ? [...history, asCandidate(currentLexicon)] : []
+		};
+		return {
+			revision: resolvedCurrent.revision,
+			record
+		};
+	}
+	if (resolvedCurrent.revision <= 1) throw new Error(`Record does not match lexicon ${normalizedNsid} at first revision`);
+	if (!history) throw new Error(`Record does not match current lexicon ${normalizedNsid} revision ${resolvedCurrent.revision} and no history provider was configured`);
+	for (const candidate of history) {
+		const historicalLexicon = parseLexiconDoc(structuredClone(candidate.lexicon));
+		if (historicalLexicon.id !== normalizedNsid) continue;
+		const candidateRevision = candidate.revision ?? historicalLexicon.revision ?? 1;
+		if (candidateRevision >= resolvedCurrent.revision) continue;
+		if (matchesLexicon(record, normalizedNsid, historicalLexicon)) {
+			if (options.returnLexicons === true) return {
+				revision: candidateRevision,
+				record,
+				lexicons: history ? [...history, asCandidate(currentLexicon)] : []
+			};
+			return {
+				revision: candidateRevision,
+				record
+			};
+		}
+	}
+	throw new Error(`Record does not match any provided lexicon revision for ${normalizedNsid}`);
+}
+/**
+* Checks if a given record matches a lexicon.
+* @param record The record to check against the lexicon.
+* @param nsid The NSID of the lexicon.
+* @param lexicon The lexicon record.
+* @returns True of the record is valid, false if not.
+*/
+function matchesLexicon(record, nsid, lexicon) {
+	if (!hasAllRequiredFields(record, lexicon)) return false;
+	const lexicons = new Lexicons([structuredClone(lexicon)]);
+	const candidateRecord = hydrateBlobs(record);
+	try {
+		lexicons.assertValidRecord(nsid, candidateRecord);
+		return true;
+	} catch (error) {
+		if (error instanceof ValidationError) return false;
+		throw error;
+	}
+}
+/**
+* Checks whether a record contains all fields required by a lexicon.
+* @param record The record to validate.
+* @param lexicon The lexicon to validate the record against.
+* @returns True if the record has all required fields, false if not.
+*/
+function hasAllRequiredFields(record, lexicon) {
+	const mainDef = lexicon.defs.main;
+	if (!mainDef || mainDef.type !== "record") return false;
+	return (mainDef.record.required ?? []).every((key) => Object.hasOwn(record, key));
+}
+/**
+* Converts the JSON blob values of a record to BlobRefs.
+* @param obj The JSON record
+* @returns The record, with all blob references as classes instead of JSON.
+*/
+function hydrateBlobs(obj) {
+	if (obj === null || typeof obj !== "object") return obj;
+	if (Array.isArray(obj)) return obj.map(hydrateBlobs);
+	if (obj.ref?.$link && typeof obj.mimeType === "string") return new BlobRef(obj.ref.$link, obj.mimeType, obj.size, obj.original);
+	const entries = Object.entries(obj).map(([key, value]) => [key, hydrateBlobs(value)]);
+	return Object.fromEntries(entries);
+}
+/**
+* Wraps a lexicon to match the `LexiconHistoryCandidate` type.
+* @param currentLexicon The lexicon to wrap.
+* @returns The wrapped lexicon, with a CID of `current`.
+*/
+function asCandidate(currentLexicon) {
+	return {
+		cid: "current",
+		lexicon: currentLexicon,
+		revision: currentLexicon.revision
+	};
+}
+//#endregion
+//#region src/util/figureOutSensibleDefault.ts
+/**
+* Tries to figure out a sensible default value based on the property's type.
+*
+* Properties with type boolean, integer, and string keep their `default` declaration as the default.
+* Arrays are instanciated as empty.
+*
+* @param property The property to figure out the default for.
+* @returns The new default value, if any.
+*/
+function figureOutSensibleDefault(property) {
+	let newDefault;
+	if ([
+		"boolean",
+		"integer",
+		"string"
+	].includes(property.type)) newDefault = property.default;
+	else if (property.type === "array") newDefault = [];
+	return newDefault;
+}
+//#endregion
+//#region src/util/isValueAllowedByProperty.ts
+/**
+* Checks if a value is allowed by a property and its constraints.
+* @param value The value to validate.
+* @param property The property the value should be used with.
+* @returns True if the value is compatible with the property, false if not.
+*/
+function isValueAllowedByProperty(value, property) {
+	const constantValue = property.const;
+	if (constantValue !== void 0) return value === constantValue;
+	switch (property.type) {
+		case "boolean": return typeof value === "boolean";
+		case "integer": {
+			if (typeof value !== "number" || !Number.isInteger(value)) return false;
+			const integerProperty = property;
+			if (integerProperty.minimum !== void 0 && value < integerProperty.minimum) return false;
+			if (integerProperty.maximum !== void 0 && value > integerProperty.maximum) return false;
+			if (integerProperty.enum && !integerProperty.enum.includes(value)) return false;
+			return true;
+		}
+		case "string": {
+			if (typeof value !== "string") return false;
+			const stringProperty = property;
+			if (stringProperty.minLength !== void 0 && value.length < stringProperty.minLength) return false;
+			if (stringProperty.maxLength !== void 0 && value.length > stringProperty.maxLength) return false;
+			if (stringProperty.enum && !stringProperty.enum.includes(value)) return false;
+			return true;
+		}
+		case "array": {
+			if (!Array.isArray(value)) return false;
+			const arrayProperty = property;
+			if (arrayProperty.minLength !== void 0 && value.length < arrayProperty.minLength) return false;
+			if (arrayProperty.maxLength !== void 0 && value.length > arrayProperty.maxLength) return false;
+			return true;
+		}
+		default: return true;
+	}
+}
+//#endregion
+//#region src/util/isDomainContained.ts
+/**
+* Checks whether a list of given values is allowed by both the current and future property.
+* @param fromProperty The current property.
+* @param toProperty The property to convert to.
+* @param domain The values that might be converted.
+* @returns True if the type can be used with the new property, false if not.
+*/
+function isTypeDomainContained(fromProperty, toProperty, domain) {
+	for (const sampleValue of domain) if (isValueAllowedByProperty(sampleValue, fromProperty) && !isValueAllowedByProperty(sampleValue, toProperty)) return false;
+	return true;
+}
+/**
+* Checks whether a string and it's constraints can be accomodated by both the current and future properties.
+* @param fromProperty The current property.
+* @param toProperty The property to convert to.
+* @returns True if the string can be used with the new property, false if not.
+*/
+function isStringDomainContained(fromProperty, toProperty) {
+	const fromString = fromProperty;
+	const toStringProperty = toProperty;
+	if (fromString.enum && toStringProperty.enum) return fromString.enum.every((value) => toStringProperty.enum.includes(value));
+	if (fromString.enum) return fromString.enum.every((value) => isValueAllowedByProperty(value, toProperty));
+	if (toStringProperty.enum) return false;
+	if (fromString.format !== void 0 && toStringProperty.format !== void 0 && fromString.format !== toStringProperty.format) return false;
+	if (fromString.format === void 0 && toStringProperty.format !== void 0) return false;
+	if (fromString.minLength === void 0 && toStringProperty.minLength !== void 0) return false;
+	if (fromString.maxLength === void 0 && toStringProperty.maxLength !== void 0) return false;
+	const oldMin = fromString.minLength ?? 0;
+	const oldMax = fromString.maxLength ?? Number.POSITIVE_INFINITY;
+	const newMin = toStringProperty.minLength ?? 0;
+	const newMax = toStringProperty.maxLength ?? Number.POSITIVE_INFINITY;
+	return newMin <= oldMin && oldMax <= newMax;
+}
+/**
+* Checks whether an integer and it's constraints can be accomodated by both the current and future properties.
+* @param fromProperty The current property.
+* @param toProperty The property to convert to.
+* @returns True if the integer value can be used with the new property, false if not.
+*/
+function isIntegerDomainContained(fromProperty, toProperty) {
+	const fromInteger = fromProperty;
+	const toInteger = toProperty;
+	if (fromInteger.enum && toInteger.enum) return fromInteger.enum.every((value) => toInteger.enum.includes(value));
+	if (fromInteger.enum) return fromInteger.enum.every((value) => isValueAllowedByProperty(value, toProperty));
+	if (toInteger.enum) return false;
+	if (fromInteger.minimum === void 0 && toInteger.minimum !== void 0) return false;
+	if (fromInteger.maximum === void 0 && toInteger.maximum !== void 0) return false;
+	const oldMin = fromInteger.minimum ?? Number.NEGATIVE_INFINITY;
+	const oldMax = fromInteger.maximum ?? Number.POSITIVE_INFINITY;
+	const newMin = toInteger.minimum ?? Number.NEGATIVE_INFINITY;
+	const newMax = toInteger.maximum ?? Number.POSITIVE_INFINITY;
+	return newMin <= oldMin && oldMax <= newMax;
+}
+//#endregion
+//#region src/util/detectKeyDifferences.ts
+/**
+* Attempts to detect which keys differ between two lexicons, and in which way.
+*
+* Keys will be separated into one of five categories:
+*
+* - unchanged
+* - converted
+* - renamed
+* - dropped
+* - created
+*
+* @param lex1 The previous lexicon that the conversion is attempted from.
+* @param lex2 The lexicon the data should be converted to.
+* @returns The differences between the lexicons.
+*/
+function detectKeyDifferences(lex1, lex2) {
+	const processedFromLex1 = [];
+	const processedFromLex2 = [];
+	const unchanged = [];
+	const converted = [];
+	const renamed = [];
+	const dropped = [];
+	const created = [];
+	const lex1Properties = Object.keys(lex1.record.properties);
+	const lex2Properties = Object.keys(lex2.record.properties);
+	for (const key of lex1Properties) {
+		const sameKeyName = lex2Properties.find((x) => x === key);
+		if (sameKeyName) {
+			processedFromLex1.push(sameKeyName);
+			processedFromLex2.push(sameKeyName);
+			const oldProperty = lex1.record.properties[key];
+			const newProperty = lex2.record.properties[sameKeyName];
+			if (canKeepExistingValue(oldProperty, newProperty)) {
+				unchanged.push(key);
+				continue;
+			}
+			if (canAttemptConversion(oldProperty, newProperty)) {
+				converted.push([
+					key,
+					oldProperty,
+					newProperty
+				]);
+				continue;
+			}
+			dropped.push(key);
+			created.push([key, figureOutSensibleDefault(newProperty)]);
+		}
+	}
+	const lex1Entries = Object.entries(lex1.record.properties);
+	const lex2Entries = Object.entries(lex2.record.properties);
+	const unprocessedLex1Keys = lex1Entries.filter(([x]) => !processedFromLex1.some((y) => y === x));
+	for (const [lex1key, lex1val] of unprocessedLex1Keys) {
+		const unprocessedLex2Keys = lex2Entries.filter(([x]) => !processedFromLex2.some((y) => y === x));
+		for (const [lex2key, lex2val] of unprocessedLex2Keys) {
+			if (!(getPropertySignature(lex1val) === getPropertySignature(lex2val))) continue;
+			if (unprocessedLex1Keys.filter(([, maybeSame]) => getPropertySignature(maybeSame) === getPropertySignature(lex2val)).length === 1) {
+				renamed.push([lex1key, lex2key]);
+				processedFromLex1.push(lex1key);
+				processedFromLex2.push(lex2key);
+				break;
+			}
+		}
+	}
+	const remainingLex1Keys = lex1Properties.filter((x) => !processedFromLex1.some((y) => y === x));
+	const remainingLex2Keys = lex2Properties.filter((x) => !processedFromLex2.some((y) => y === x));
+	for (const key of remainingLex1Keys) dropped.push(key);
+	for (const key of remainingLex2Keys) created.push([key, figureOutSensibleDefault(lex2.record.properties[key])]);
+	return {
+		unchanged,
+		converted,
+		renamed,
+		dropped,
+		created
+	};
+}
+/**
+* Checks whether a given property can reasonably be converted to another type.
+*
+* The following conversions are considered sensible:
+*
+* - boolean → integer
+* - boolean → string
+* - integer → boolean
+* - integer → string
+* - string → boolean
+* - string → integer
+*
+* @param fromProperty The property to be converted from.
+* @param toProperty The property to be converted to.
+* @returns Whether the conversion can be done.
+*/
+function canAttemptConversion(fromProperty, toProperty) {
+	if (fromProperty.type === toProperty.type) return false;
+	return fromProperty.type === "boolean" && toProperty.type === "integer" || fromProperty.type === "boolean" && toProperty.type === "string" || fromProperty.type === "integer" && toProperty.type === "boolean" || fromProperty.type === "integer" && toProperty.type === "string" || fromProperty.type === "string" && toProperty.type === "boolean" || fromProperty.type === "string" && toProperty.type === "integer";
+}
+/**
+* Detects whether the value of a given property can be kept when converting to a different type.
+* @param fromProperty The property that will be converted from.
+* @param toProperty The property that will be converted to.
+* @returns Whether the conversion can be done while preserving the value.
+*/
+function canKeepExistingValue(fromProperty, toProperty) {
+	if (fromProperty.type !== toProperty.type) return false;
+	if (getPropertySignature(fromProperty) === getPropertySignature(toProperty)) return true;
+	switch (fromProperty.type) {
+		case "boolean": return isTypeDomainContained(fromProperty, toProperty, [false, true]);
+		case "integer": return isIntegerDomainContained(fromProperty, toProperty);
+		case "string": return isStringDomainContained(fromProperty, toProperty);
+		case "array": {
+			const fromArray = fromProperty;
+			const toArray = toProperty;
+			const oldMin = fromArray.minLength ?? 0;
+			const oldMax = fromArray.maxLength;
+			const newMin = toArray.minLength ?? 0;
+			const newMax = toArray.maxLength;
+			return newMin <= oldMin && (newMax === void 0 || oldMax !== void 0 && oldMax <= newMax);
+		}
+		default: return false;
+	}
+}
+/**
+* Returns the stringified version of a normalized property.
+* @param property The property to get the signature for.
+* @returns The signature of the property.
+*/
+function getPropertySignature(property) {
+	return JSON.stringify(normalizeForComparison(property));
+}
+/**
+* Normalizes a given value so it can be compared to another.
+* @param value The value to normalize.
+* @returns The normalized value.
+*/
+function normalizeForComparison(value) {
+	if (Array.isArray(value)) {
+		const normalizedArray = value.map((item) => normalizeForComparison(item));
+		if (normalizedArray.every((item) => [
+			"string",
+			"number",
+			"boolean"
+		].includes(typeof item))) return [...normalizedArray].sort((a, b) => String(a).localeCompare(String(b)));
+		return normalizedArray;
+	}
+	if (value && typeof value === "object") {
+		const normalizedEntries = Object.entries(value).filter(([key]) => key !== "description").sort(([a], [b]) => a.localeCompare(b)).map(([key, entryValue]) => [key, normalizeForComparison(entryValue)]);
+		return Object.fromEntries(normalizedEntries);
+	}
+	return value;
+}
+//#endregion
+//#region src/shiftRecord.ts
+const CONVERSION_FAILED = Symbol("conversion-failed");
+/**
+* Shifts a given record along an upgrade path.
+*
+* @param record The record to shift.
+* @param upgradePath An array of lexicon history candidates in correct order of revisions.
+* @returns The shifted record.
+*/
+function shiftRecord(record, upgradePath) {
+	const upgradeStepCount = upgradePath.length - 1;
+	const recordTemplate = structuredClone(record);
+	for (let i = 0; i < upgradeStepCount; i++) {
+		const currentLexicon = upgradePath[i];
+		const nextLexicon = upgradePath[i + 1];
+		const { created, dropped, renamed, converted } = detectKeyDifferences(ensureLexRecord(currentLexicon.lexicon), ensureLexRecord(nextLexicon.lexicon));
+		for (const [key, fromProperty, toProperty] of converted) {
+			const convertedValue = tryConvertPropertyValue(recordTemplate[key], fromProperty, toProperty);
+			recordTemplate[key] = convertedValue === CONVERSION_FAILED ? figureOutSensibleDefault(toProperty) : convertedValue;
+		}
+		for (const key of dropped) delete recordTemplate[key];
+		for (const [oldKey, newKey] of renamed) {
+			recordTemplate[newKey] = structuredClone(recordTemplate[oldKey]);
+			delete recordTemplate[oldKey];
+		}
+		for (const [key, defaultVal] of created) recordTemplate[key] = defaultVal;
+	}
+	return recordTemplate;
+}
+/**
+* Attempts to convert a given value from one property to another.
+* @param value The value to convert.
+* @param fromProperty The property to convert from.
+* @param toProperty The property to convert to.
+* @returns The converted value.
+*/
+function tryConvertPropertyValue(value, fromProperty, toProperty) {
+	if (isValueAllowedByProperty(value, toProperty)) return value;
+	let convertedValue = CONVERSION_FAILED;
+	if (fromProperty.type === "boolean" && toProperty.type === "integer" && typeof value === "boolean") convertedValue = value ? 1 : 0;
+	else if (fromProperty.type === "boolean" && toProperty.type === "string" && typeof value === "boolean") convertedValue = value ? "true" : "false";
+	else if (fromProperty.type === "integer" && toProperty.type === "boolean" && typeof value === "number") convertedValue = value !== 0;
+	else if (fromProperty.type === "integer" && toProperty.type === "string" && typeof value === "number") convertedValue = value.toString();
+	else if (fromProperty.type === "string" && toProperty.type === "boolean" && typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") convertedValue = true;
+		else if (normalized === "false") convertedValue = false;
+	} else if (fromProperty.type === "string" && toProperty.type === "integer" && typeof value === "string") {
+		const trimmed = value.trim();
+		if (/^-?\d+$/.test(trimmed)) convertedValue = Number.parseInt(trimmed, 10);
+	}
+	if (convertedValue === CONVERSION_FAILED) return CONVERSION_FAILED;
+	return isValueAllowedByProperty(convertedValue, toProperty) ? convertedValue : CONVERSION_FAILED;
+}
+/**
+* Ensures a given lexicon is a record lexicon.
+* @param lexicon The lexicon to check.
+* @returns A typed record lexicon.
+*/
+function ensureLexRecord(lexicon) {
+	const typedLexicon = lexicon;
+	if (!typedLexicon.defs?.main) throw new Error("Provided lexicon does not have a main definition. Unable to process.");
+	if (typedLexicon.defs.main.type !== "record") throw new Error("Provided lexicon's main definition is not a record. Unable to process.");
+	return typedLexicon.defs.main;
+}
+//#endregion
+//#region src/shift.ts
+/**
+* Shifts a record from its current lexicon revision to another one, by either upshifting or downshifting.
+*
+* @param record The record to shift.
+* @param newRevision The revision to shift to.
+* @param options The options for this function.
+*/
+async function shift(record, newRevision, options = {}) {
+	const { revision: oldRevision, lexicons } = await identify(record, {
+		...options,
+		returnLexicons: true
+	});
+	if (oldRevision === newRevision) return {
+		oldRevision,
+		newRevision,
+		record
+	};
+	const lowerRevision = newRevision > oldRevision ? oldRevision : newRevision;
+	const higherRevision = newRevision === lowerRevision ? oldRevision : newRevision;
+	return {
+		oldRevision,
+		newRevision,
+		record: shiftRecord(record, lexicons.filter((x) => x.revision >= lowerRevision && x.revision <= higherRevision).sort((a, b) => {
+			if (newRevision > oldRevision) return (a.revision ?? 0) - (b.revision ?? 0);
+			return (b.revision ?? 0) - (a.revision ?? 0);
+		}))
+	};
+}
+//#endregion
+export { identify, shift };

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "lexshift",
+	"version": "0.0.1",
+	"description": "Identify and migrate AT Protocol records across lexicon revisions.",
+	"type": "module",
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"sideEffects": false,
+	"keywords": [
+		"atproto",
+		"at protocol",
+		"lexicon",
+		"schema",
+		"migration"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/louisescher/lexshift.git",
+		"directory": "packages/lexshift"
+	},
+	"homepage": "https://github.com/louisescher/lexshift/tree/main/packages/lexshift",
+	"bugs": {
+		"url": "https://github.com/louisescher/lexshift/issues"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"check-types": "tsc -b",
+		"prepack": "pnpm run build"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@atproto/lex-resolver": "^0.0.23",
+		"@atproto/lexicon": "^0.6.2"
+	},
+	"devDependencies": {
+		"tsdown": "^0.21.9",
+		"typescript": "^5.9.3"
+	}
+}