rotorise 0.2.5 → 0.3.3

package/dist/Rotorise.d.cts

@@ -1,44 +1,22 @@
-type KeysOfUnion<ObjectType> = ObjectType extends unknown
-    ? keyof ObjectType
-    : never
-type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <
-    G,
->() => G extends U ? 1 : 2
-    ? true
-    : false
-
-type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never
-
-type ExactObject<ParameterType, InputType> = {
-    [Key in keyof ParameterType]: Exact<
-        ParameterType[Key],
-        Key extends keyof InputType ? InputType[Key] : never
-    >
-} & Record<Exclude<keyof InputType, KeysOfUnion<ParameterType>>, never>
-
-type Exact<ParameterType, InputType> = IsEqual<
-    ParameterType,
-    InputType
-> extends true
-    ? ParameterType
-    : // Convert union of array to array of union: A[] & B[] => (A & B)[]
-      ParameterType extends unknown[]
-      ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
-      : // In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
-        ParameterType extends readonly unknown[]
-        ? ReadonlyArray<
-              Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>
-          >
-        : ParameterType extends object
-          ? ExactObject<ParameterType, InputType>
-          : ParameterType
+// Lighter Exact implementation — catches excess top-level properties only.
+// Does not recursively check nested objects/arrays. This is intentional:
+// DynamoDB entity shapes are flat at the key level.
+type Exact<Shape, Candidate> = Candidate & {
+    [K in keyof Candidate]: K extends keyof Shape ? Candidate[K] : never
+}
 
 type ValueOf<
     ObjectType,
     ValueType = keyof ObjectType,
 > = ValueType extends keyof ObjectType ? ObjectType[ValueType] : never
 
-type evaluate<T> = { [K in keyof T]: T[K] } & unknown
+/**
+ * Force an operation like `{ a: 0 } & { b: 1 }` to be computed so that it displays `{ a: 0; b: 1 }`.
+ * This version is distributive, meaning it will preserve union types while flattening each member.
+ */
+type show<T> = T extends unknown
+    ? { [K in keyof T]: T[K] } & unknown
+    : never
 
 type DistributivePick<T, K> = T extends unknown
     ? K extends keyof T
@@ -54,48 +32,63 @@ type SliceFromStart<
     T,
     End extends number,
     Acc extends unknown[] = [],
-> = T extends unknown[]
-    ? Acc['length'] extends End
-        ? Acc
-        : T extends [infer Head, ...infer Tail]
-          ? SliceFromStart<Tail, End, [...Acc, Head]>
-          : Acc
-    : never
+> = End extends 0
+    ? []
+    : End extends 1
+      ? T extends [infer Head, ...unknown[]]
+          ? [Head]
+          : []
+      : T extends unknown[]
+        ? Acc['length'] extends End
+            ? Acc
+            : T extends [infer Head, ...infer Tail]
+              ? SliceFromStart<Tail, End, [...Acc, Head]>
+              : Acc
+        : never
 
 type MergeIntersectionObject<T, Keys = keyof T> = {
     [K in Keys]: T[K]
 }
-// type t = MergeIntersectionObject<
-//     { a: 'a1'; b: 1n; extra: 'extra' } | { a: 'a2'; b: 2 }
-// >
 
 type NonEmptyArray<T> = [T, ...T[]]
 
 type Replace<T, U, V> = T extends U ? V : T
 
-type CompositeKeyParamsImpl<Entity, InputSpec extends InputSpecShape, skip extends number = 1> = Entity extends unknown ? evaluate<Pick<Entity, extractHeadOrPass<SliceFromStart<InputSpec, number extends skip ? 1 : skip>[number]> & keyof Entity> & Partial<Pick<Entity, extractHeadOrPass<InputSpec[number]> & keyof Entity>>> : never;
+/**
+ * Represents a type-level error message. Used to provide helpful feedback in the IDE.
+ */
+declare const errorMessage: unique symbol
+type ErrorMessage<T extends string> = {
+    readonly [errorMessage]: T
+}
+
+type TransformOverride<Spec extends InputSpecShape, K, Fallback, Matched = Extract<Spec[number], [K, (...args: any[]) => any, ...any[]]>> = [Matched] extends [never] ? Fallback : (Matched extends [any, (x: infer P) => any, ...any[]] ? (x: P) => void : never) extends (x: infer I) => void ? I : Fallback;
+type CompositeKeyParamsImpl<Entity, InputSpec extends InputSpecShape, skip extends number = 1> = Entity extends unknown ? show<{
+    [K in extractHeadOrPass<SliceFromStart<InputSpec, number extends skip ? 1 : skip>[number]> & keyof Entity]: TransformOverride<InputSpec, K, Entity[K]>;
+} & {
+    [K in extractHeadOrPass<InputSpec[number]> & keyof Entity]?: TransformOverride<InputSpec, K, Entity[K]>;
+}> : never;
 type CompositeKeyParams<Entity extends Record<string, unknown>, FullSpec extends InputSpec<MergeIntersectionObject<Entity>>[], skip extends number = 1> = CompositeKeyParamsImpl<Entity, FullSpec, skip>;
-type CompositeKeyBuilderImpl<Entity, Spec, Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = Entity extends unknown ? Join<CompositeKeyRec<Entity, number extends Deep ? Spec : SliceFromStart<Spec, Deep>>, Separator, boolean extends isPartial ? false : isPartial> : never;
+type CompositeKeyBuilderImpl<Entity, Spec, Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = Entity extends unknown ? CompositeKeyStringBuilder<Entity, [
+    Deep
+] extends [never] ? Spec : number extends Deep ? Spec : SliceFromStart<Spec, Deep>, Separator, boolean extends isPartial ? false : isPartial> : never;
 type CompositeKeyBuilder<Entity extends Record<string, unknown>, Spec extends InputSpec<MergeIntersectionObject<Entity>>[], Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = CompositeKeyBuilderImpl<Entity, Spec, Separator, Deep, isPartial>;
 type joinable = string | number | bigint | boolean | null | undefined;
-type joinablePair = [joinable, joinable];
-type Join<Pairs, Separator extends string, KeepIntermediate extends boolean = false, Acc extends string = '', AllAcc extends string = never> = Pairs extends [infer Head extends joinablePair, ...infer Tail] ? Join<Tail, Separator, KeepIntermediate, Acc extends '' ? [Head[0]] extends [never] ? `${Head[1]}` : `${Head[0]}${Separator}${Head[1]}` : [Head[0]] extends [never] ? `${Acc}${Separator}${Head[1]}` : `${Acc}${Separator}${Head[0]}${Separator}${Head[1]}`, KeepIntermediate extends true ? AllAcc | (Acc extends '' ? never : Acc) : never> : AllAcc | Acc;
-type ExtractHelper<Key, Value> = Value extends joinable ? [Key, Value] : Value extends {
+type ExtractHelper<Key, Value> = Value extends object ? Value extends {
     tag: infer Tag extends string;
     value: infer Value extends joinable;
 } ? [Tag, Value] : Value extends {
-    tag?: undefined;
     value: infer Value extends joinable;
-} ? [never, Value] : never;
+} ? [never, Value] : never : [Key, Value];
 type ExtractPair<Entity, Spec> = Spec extends [
     infer Key extends string,
     (...key: any[]) => infer Value,
     ...unknown[]
 ] ? ExtractHelper<Uppercase<Key>, Value> : Spec extends keyof Entity & string ? [Uppercase<Spec>, Entity[Spec] & joinable] : never;
-type CompositeKeyRec<Entity, Spec, Acc extends joinablePair[] = [], KeysCache extends string = keyof Entity & string> = Spec extends [infer Head, ...infer Tail] ? CompositeKeyRec<Entity, Tail, [
-    ...Acc,
-    ExtractPair<Entity, Head>
-], KeysCache> : Acc;
+type CompositeKeyStringBuilder<Entity, Spec, Separator extends string, KeepIntermediate extends boolean, Acc extends string = '', AllAcc extends string = never> = Spec extends [infer Head, ...infer Tail] ? ExtractPair<Entity, Head> extends [
+    infer Key extends joinable,
+    infer Value extends joinable
+] ? CompositeKeyStringBuilder<Entity, Tail, Separator, KeepIntermediate, Acc extends '' ? [Key] extends [never] ? `${Value}` : `${Key}${Separator}${Value}` : [Key] extends [never] ? `${Acc}${Separator}${Value}` : `${Acc}${Separator}${Key}${Separator}${Value}`, KeepIntermediate extends true ? AllAcc | (Acc extends '' ? never : Acc) : never> : never : AllAcc | Acc;
 type DiscriminatedSchemaShape = {
     discriminator: PropertyKey;
     spec: {
@@ -107,9 +100,18 @@ type TransformShape = {
     tag?: string;
     value: joinable;
 } | joinable;
-type TableEntryImpl<Entity, Schema, Separator extends string = '#'> = Entity extends unknown ? {
-    [Key in keyof Schema]: Schema[Key] extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Schema[Key]['spec'], ValueOf<Entity, Schema[Key]['discriminator']>>, Separator> : ProcessKey<Entity, Schema[Key], Separator>;
-} & Entity : never;
+type ComputeTableKeyType<Entity, Spec, Separator extends string, NullAs extends never | undefined = never> = Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, number, false> : Spec extends keyof Entity ? Replace<Entity[Spec], null, undefined> : Spec extends null ? NullAs : never;
+type TableEntryImpl<Entity, Schema, Separator extends string = '#'> = Entity extends unknown ? show<{
+    readonly [Key in keyof Schema]: Schema[Key] extends DiscriminatedSchemaShape ? ComputeTableKeyType<Entity, ValueOf<Schema[Key]['spec'], ValueOf<Entity, Schema[Key]['discriminator']>>, Separator> : Schema[Key] extends keyof Entity | InputSpecShape | null ? ComputeTableKeyType<Entity, Schema[Key], Separator> : ErrorMessage<'Invalid schema definition'>;
+} & Entity> : never;
+/**
+ * Represents a complete DynamoDB table entry, combining the original entity
+ * with its computed internal and global keys.
+ *
+ * @template Entity The base entity type.
+ * @template Schema The schema defining the table keys.
+ * @template Separator The string used to join composite key components (default: '#').
+ */
 type TableEntry<Entity extends Record<string, unknown>, Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = '#'> = TableEntryImpl<Entity, Schema, Separator>;
 type InputSpec<E> = {
     [key in keyof E]: (undefined extends E[key] ? [
@@ -131,39 +133,90 @@ type DiscriminatedSchema<Entity, E> = {
     } : never;
 }[keyof E];
 type FullKeySpec<Entity> = FullKeySpecSimple<Entity> | DiscriminatedSchema<Entity, MergeIntersectionObject<Entity>>;
-type ProcessSpecType<Entity, Spec, Config extends SpecConfigShape> = Spec extends string ? DistributivePick<Entity, Spec> : Spec extends InputSpecShape ? CompositeKeyParamsImpl<Entity, Spec, Config['allowPartial'] extends true ? 1 : Extract<Config['depth'], number>> : never;
+declare class RotoriseError extends Error {
+    constructor(message: string);
+}
+type ProcessSpecType<Entity, Spec, Config extends SpecConfigShape> = Spec extends string ? DistributivePick<Entity, Spec> : Spec extends InputSpecShape ? CompositeKeyParamsImpl<Entity, Spec, Config['allowPartial'] extends true ? 1 : Extract<Config['depth'], number>> : Spec extends null | undefined ? unknown : ErrorMessage<'Invalid Spec: Expected string, InputSpecShape, null or undefined'>;
 type SpecConfig<Spec> = Spec extends string ? never : SpecConfigShape;
 type SpecConfigShape = {
     depth?: number;
     allowPartial?: boolean;
     enforceBoundary?: boolean;
 };
-type VariantType<Entity, K extends PropertyKey, V extends PropertyKey> = [
+type ExtractVariant<Entity, K extends PropertyKey, V extends PropertyKey> = [
+    Entity
+] extends [never] ? never : Extract<Entity, {
+    [k in K]: V;
+}>;
+type TagVariant<Entity, K extends PropertyKey, V extends PropertyKey> = [
     Entity
 ] extends [never] ? {
     [k in K]: V;
 } : Entity & {
     [k in K]: V;
 };
-type ProcessVariant<Entity, K extends PropertyKey, V extends PropertyKey, Spec extends DiscriminatedSchemaShape, Config extends SpecConfigShape> = VariantType<ProcessSpecType<VariantType<Entity, K, V>, Spec['spec'][V & keyof Spec['spec']], Config>, K, V>;
-type OptimizedAttributes<Entity, Spec, Config extends SpecConfigShape> = Spec extends DiscriminatedSchemaShape ? {
+type ProcessVariant<Entity, K extends PropertyKey, V extends PropertyKey, Spec extends DiscriminatedSchemaShape, Config extends SpecConfigShape, VariantSpec = Spec['spec'][V & keyof Spec['spec']]> = TagVariant<VariantSpec extends null | undefined ? unknown : ProcessSpecType<ExtractVariant<Entity, K, V>, VariantSpec, Config>, K, V>;
+type OptimizedAttributes<Entity, Spec, Config extends SpecConfigShape> = show<Spec extends DiscriminatedSchemaShape ? {
     [K in Spec['discriminator']]: {
         [V in keyof Spec['spec']]: ProcessVariant<Entity, K, V, Spec, Config>;
     }[keyof Spec['spec']];
-}[Spec['discriminator']] : ProcessSpecType<Entity, Spec, Config>;
-type ProcessKey<Entity, Spec, Separator extends string, NullAs extends never | undefined = never, Config extends SpecConfigShape = SpecConfigShape, Attributes = Pick<Entity, Spec & keyof Entity>> = [Entity] extends [never] ? never : Spec extends keyof Entity ? Replace<ValueOf<Attributes>, null, undefined> : Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, Exclude<Config['depth'], undefined>, Exclude<Config['allowPartial'], undefined>> : Spec extends null ? NullAs : never;
-type OptimizedBuildedKey<Entity, Spec, Separator extends string, Config extends SpecConfigShape, Attributes> = Entity extends unknown ? Spec extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Spec['spec'], ValueOf<Entity, Spec['discriminator']>>, Separator, undefined, Config, Attributes> : ProcessKey<Entity, Spec, Separator, undefined, Config, Attributes> : never;
+}[Spec['discriminator']] : ProcessSpecType<Entity, Spec, Config>>;
+type ProcessKey<Entity, Spec, Separator extends string, NullAs extends never | undefined = never, Config extends SpecConfigShape = SpecConfigShape, Attributes = Pick<Entity, Spec & keyof Entity>> = [Entity] extends [never] ? never : Spec extends keyof Entity ? Replace<ValueOf<Attributes>, null, undefined> : Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, Exclude<Config['depth'], undefined>, Exclude<Config['allowPartial'], undefined>> : Spec extends null | undefined ? NullAs : ErrorMessage<'Invalid Spec'>;
+type OptimizedBuiltKey<Entity, Spec, Separator extends string, Config extends SpecConfigShape, Attributes> = Entity extends unknown ? show<Spec extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Spec['spec'], ValueOf<Entity, Spec['discriminator']>>, Separator, undefined, Config, Attributes> : ProcessKey<Entity, Spec, Separator, undefined, Config, Attributes>> : never;
 type TableEntryDefinition<Entity, Schema, Separator extends string> = {
-    toEntry: <const ExactEntity extends Exact<Entity, ExactEntity>>(item: ExactEntity) => TableEntryImpl<ExactEntity, Schema, Separator>;
+    /**
+     * Converts a raw entity into a complete table entry with all keys computed.
+     * Use this when preparing items for insertion into DynamoDB.
+     */
+    toEntry: <const ExactEntity>(item: Exact<Entity, ExactEntity>) => TableEntryImpl<ExactEntity, Schema, Separator>;
+    /**
+     * Extracts the raw entity from a table entry by removing all computed keys.
+     * Use this when processing items retrieved from DynamoDB.
+     */
     fromEntry: <const Entry extends TableEntryImpl<Entity, Schema, Separator>>(entry: Entry) => DistributiveOmit<Entry, keyof Schema>;
+    /**
+     * Generates a specific key for the given entity attributes.
+     * Supports partial keys and depth limiting for query operations.
+     *
+     * @param key The name of the key to generate (e.g., 'PK', 'GSIPK').
+     * @param attributes the object containing the values needed to build the key.
+     * @param config Optional configuration for partial keys or depth limiting.
+     */
     key: <const Key extends keyof Schema, const Config extends SpecConfig<Spec>, const Attributes extends OptimizedAttributes<Entity, Spec, Config_>, Spec = Schema[Key], Config_ extends SpecConfigShape = [SpecConfigShape] extends [Config] ? {
         depth?: undefined;
         allowPartial?: undefined;
         enforceBoundary?: boolean;
-    } : Config>(key: Key, attributes: Attributes, config?: Config) => OptimizedBuildedKey<Attributes, Spec, Separator, Config_, Attributes>;
+    } : Config>(key: Key, attributes: Attributes, config?: Config) => OptimizedBuiltKey<Attributes, Spec, Separator, Config_, Attributes>;
+    /**
+     * A zero-runtime inference helper. Use this with `typeof` to get the
+     * total type of a table entry.
+     */
     infer: TableEntryImpl<Entity, Schema, Separator>;
+    /**
+     * Creates a proxy to generate property paths as strings.
+     * Useful for building UpdateExpressions or ProjectionExpressions.
+     *
+     * @example
+     * table.path().data.nested.property.toString() // returns "data.nested.property"
+     */
     path: () => TableEntryImpl<Entity, Schema, Separator>;
 };
-declare const tableEntry: <const Entity extends Record<string, unknown>>() => <const Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = "#">(schema: Schema, separator?: Separator) => TableEntryDefinition<Entity, Schema, Separator>;
+/**
+ * Entry point for defining a DynamoDB table schema with Rotorise.
+ *
+ * @template Entity The base entity type that this table represents.
+ * @returns A builder function that accepts the schema and an optional separator.
+ *
+ * Note: the double-call `<Entity>()(schema)` is required for partial type parameter inference.
+ *
+ * @example
+ * const userTable = tableEntry<User>()({
+ *   PK: ["orgId", "id"],
+ *   SK: "role"
+ * })
+ */
+declare const tableEntry: <const Entity extends Record<string, unknown>>() => <const Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = "#">(schema: Schema, ...[separator]: [Separator] extends [
+    ''
+] ? [ErrorMessage<'Separator must not be an empty string'>] : [separator?: Separator]) => TableEntryDefinition<Entity, Schema, Separator>;
 
-export { type CompositeKeyBuilder, type CompositeKeyParams, type CompositeKeyParamsImpl, type TableEntry, type TransformShape, tableEntry };
+export { type CompositeKeyBuilder, type CompositeKeyParams, type CompositeKeyParamsImpl, RotoriseError, type TableEntry, type TransformShape, tableEntry };

package/dist/Rotorise.d.ts

@@ -1,44 +1,22 @@
-type KeysOfUnion<ObjectType> = ObjectType extends unknown
-    ? keyof ObjectType
-    : never
-type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <
-    G,
->() => G extends U ? 1 : 2
-    ? true
-    : false
-
-type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never
-
-type ExactObject<ParameterType, InputType> = {
-    [Key in keyof ParameterType]: Exact<
-        ParameterType[Key],
-        Key extends keyof InputType ? InputType[Key] : never
-    >
-} & Record<Exclude<keyof InputType, KeysOfUnion<ParameterType>>, never>
-
-type Exact<ParameterType, InputType> = IsEqual<
-    ParameterType,
-    InputType
-> extends true
-    ? ParameterType
-    : // Convert union of array to array of union: A[] & B[] => (A & B)[]
-      ParameterType extends unknown[]
-      ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
-      : // In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
-        ParameterType extends readonly unknown[]
-        ? ReadonlyArray<
-              Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>
-          >
-        : ParameterType extends object
-          ? ExactObject<ParameterType, InputType>
-          : ParameterType
+// Lighter Exact implementation — catches excess top-level properties only.
+// Does not recursively check nested objects/arrays. This is intentional:
+// DynamoDB entity shapes are flat at the key level.
+type Exact<Shape, Candidate> = Candidate & {
+    [K in keyof Candidate]: K extends keyof Shape ? Candidate[K] : never
+}
 
 type ValueOf<
     ObjectType,
     ValueType = keyof ObjectType,
 > = ValueType extends keyof ObjectType ? ObjectType[ValueType] : never
 
-type evaluate<T> = { [K in keyof T]: T[K] } & unknown
+/**
+ * Force an operation like `{ a: 0 } & { b: 1 }` to be computed so that it displays `{ a: 0; b: 1 }`.
+ * This version is distributive, meaning it will preserve union types while flattening each member.
+ */
+type show<T> = T extends unknown
+    ? { [K in keyof T]: T[K] } & unknown
+    : never
 
 type DistributivePick<T, K> = T extends unknown
     ? K extends keyof T
@@ -54,48 +32,63 @@ type SliceFromStart<
     T,
     End extends number,
     Acc extends unknown[] = [],
-> = T extends unknown[]
-    ? Acc['length'] extends End
-        ? Acc
-        : T extends [infer Head, ...infer Tail]
-          ? SliceFromStart<Tail, End, [...Acc, Head]>
-          : Acc
-    : never
+> = End extends 0
+    ? []
+    : End extends 1
+      ? T extends [infer Head, ...unknown[]]
+          ? [Head]
+          : []
+      : T extends unknown[]
+        ? Acc['length'] extends End
+            ? Acc
+            : T extends [infer Head, ...infer Tail]
+              ? SliceFromStart<Tail, End, [...Acc, Head]>
+              : Acc
+        : never
 
 type MergeIntersectionObject<T, Keys = keyof T> = {
     [K in Keys]: T[K]
 }
-// type t = MergeIntersectionObject<
-//     { a: 'a1'; b: 1n; extra: 'extra' } | { a: 'a2'; b: 2 }
-// >
 
 type NonEmptyArray<T> = [T, ...T[]]
 
 type Replace<T, U, V> = T extends U ? V : T
 
-type CompositeKeyParamsImpl<Entity, InputSpec extends InputSpecShape, skip extends number = 1> = Entity extends unknown ? evaluate<Pick<Entity, extractHeadOrPass<SliceFromStart<InputSpec, number extends skip ? 1 : skip>[number]> & keyof Entity> & Partial<Pick<Entity, extractHeadOrPass<InputSpec[number]> & keyof Entity>>> : never;
+/**
+ * Represents a type-level error message. Used to provide helpful feedback in the IDE.
+ */
+declare const errorMessage: unique symbol
+type ErrorMessage<T extends string> = {
+    readonly [errorMessage]: T
+}
+
+type TransformOverride<Spec extends InputSpecShape, K, Fallback, Matched = Extract<Spec[number], [K, (...args: any[]) => any, ...any[]]>> = [Matched] extends [never] ? Fallback : (Matched extends [any, (x: infer P) => any, ...any[]] ? (x: P) => void : never) extends (x: infer I) => void ? I : Fallback;
+type CompositeKeyParamsImpl<Entity, InputSpec extends InputSpecShape, skip extends number = 1> = Entity extends unknown ? show<{
+    [K in extractHeadOrPass<SliceFromStart<InputSpec, number extends skip ? 1 : skip>[number]> & keyof Entity]: TransformOverride<InputSpec, K, Entity[K]>;
+} & {
+    [K in extractHeadOrPass<InputSpec[number]> & keyof Entity]?: TransformOverride<InputSpec, K, Entity[K]>;
+}> : never;
 type CompositeKeyParams<Entity extends Record<string, unknown>, FullSpec extends InputSpec<MergeIntersectionObject<Entity>>[], skip extends number = 1> = CompositeKeyParamsImpl<Entity, FullSpec, skip>;
-type CompositeKeyBuilderImpl<Entity, Spec, Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = Entity extends unknown ? Join<CompositeKeyRec<Entity, number extends Deep ? Spec : SliceFromStart<Spec, Deep>>, Separator, boolean extends isPartial ? false : isPartial> : never;
+type CompositeKeyBuilderImpl<Entity, Spec, Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = Entity extends unknown ? CompositeKeyStringBuilder<Entity, [
+    Deep
+] extends [never] ? Spec : number extends Deep ? Spec : SliceFromStart<Spec, Deep>, Separator, boolean extends isPartial ? false : isPartial> : never;
 type CompositeKeyBuilder<Entity extends Record<string, unknown>, Spec extends InputSpec<MergeIntersectionObject<Entity>>[], Separator extends string = '#', Deep extends number = number, isPartial extends boolean = false> = CompositeKeyBuilderImpl<Entity, Spec, Separator, Deep, isPartial>;
 type joinable = string | number | bigint | boolean | null | undefined;
-type joinablePair = [joinable, joinable];
-type Join<Pairs, Separator extends string, KeepIntermediate extends boolean = false, Acc extends string = '', AllAcc extends string = never> = Pairs extends [infer Head extends joinablePair, ...infer Tail] ? Join<Tail, Separator, KeepIntermediate, Acc extends '' ? [Head[0]] extends [never] ? `${Head[1]}` : `${Head[0]}${Separator}${Head[1]}` : [Head[0]] extends [never] ? `${Acc}${Separator}${Head[1]}` : `${Acc}${Separator}${Head[0]}${Separator}${Head[1]}`, KeepIntermediate extends true ? AllAcc | (Acc extends '' ? never : Acc) : never> : AllAcc | Acc;
-type ExtractHelper<Key, Value> = Value extends joinable ? [Key, Value] : Value extends {
+type ExtractHelper<Key, Value> = Value extends object ? Value extends {
     tag: infer Tag extends string;
     value: infer Value extends joinable;
 } ? [Tag, Value] : Value extends {
-    tag?: undefined;
     value: infer Value extends joinable;
-} ? [never, Value] : never;
+} ? [never, Value] : never : [Key, Value];
 type ExtractPair<Entity, Spec> = Spec extends [
     infer Key extends string,
     (...key: any[]) => infer Value,
     ...unknown[]
 ] ? ExtractHelper<Uppercase<Key>, Value> : Spec extends keyof Entity & string ? [Uppercase<Spec>, Entity[Spec] & joinable] : never;
-type CompositeKeyRec<Entity, Spec, Acc extends joinablePair[] = [], KeysCache extends string = keyof Entity & string> = Spec extends [infer Head, ...infer Tail] ? CompositeKeyRec<Entity, Tail, [
-    ...Acc,
-    ExtractPair<Entity, Head>
-], KeysCache> : Acc;
+type CompositeKeyStringBuilder<Entity, Spec, Separator extends string, KeepIntermediate extends boolean, Acc extends string = '', AllAcc extends string = never> = Spec extends [infer Head, ...infer Tail] ? ExtractPair<Entity, Head> extends [
+    infer Key extends joinable,
+    infer Value extends joinable
+] ? CompositeKeyStringBuilder<Entity, Tail, Separator, KeepIntermediate, Acc extends '' ? [Key] extends [never] ? `${Value}` : `${Key}${Separator}${Value}` : [Key] extends [never] ? `${Acc}${Separator}${Value}` : `${Acc}${Separator}${Key}${Separator}${Value}`, KeepIntermediate extends true ? AllAcc | (Acc extends '' ? never : Acc) : never> : never : AllAcc | Acc;
 type DiscriminatedSchemaShape = {
     discriminator: PropertyKey;
     spec: {
@@ -107,9 +100,18 @@ type TransformShape = {
     tag?: string;
     value: joinable;
 } | joinable;
-type TableEntryImpl<Entity, Schema, Separator extends string = '#'> = Entity extends unknown ? {
-    [Key in keyof Schema]: Schema[Key] extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Schema[Key]['spec'], ValueOf<Entity, Schema[Key]['discriminator']>>, Separator> : ProcessKey<Entity, Schema[Key], Separator>;
-} & Entity : never;
+type ComputeTableKeyType<Entity, Spec, Separator extends string, NullAs extends never | undefined = never> = Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, number, false> : Spec extends keyof Entity ? Replace<Entity[Spec], null, undefined> : Spec extends null ? NullAs : never;
+type TableEntryImpl<Entity, Schema, Separator extends string = '#'> = Entity extends unknown ? show<{
+    readonly [Key in keyof Schema]: Schema[Key] extends DiscriminatedSchemaShape ? ComputeTableKeyType<Entity, ValueOf<Schema[Key]['spec'], ValueOf<Entity, Schema[Key]['discriminator']>>, Separator> : Schema[Key] extends keyof Entity | InputSpecShape | null ? ComputeTableKeyType<Entity, Schema[Key], Separator> : ErrorMessage<'Invalid schema definition'>;
+} & Entity> : never;
+/**
+ * Represents a complete DynamoDB table entry, combining the original entity
+ * with its computed internal and global keys.
+ *
+ * @template Entity The base entity type.
+ * @template Schema The schema defining the table keys.
+ * @template Separator The string used to join composite key components (default: '#').
+ */
 type TableEntry<Entity extends Record<string, unknown>, Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = '#'> = TableEntryImpl<Entity, Schema, Separator>;
 type InputSpec<E> = {
     [key in keyof E]: (undefined extends E[key] ? [
@@ -131,39 +133,90 @@ type DiscriminatedSchema<Entity, E> = {
     } : never;
 }[keyof E];
 type FullKeySpec<Entity> = FullKeySpecSimple<Entity> | DiscriminatedSchema<Entity, MergeIntersectionObject<Entity>>;
-type ProcessSpecType<Entity, Spec, Config extends SpecConfigShape> = Spec extends string ? DistributivePick<Entity, Spec> : Spec extends InputSpecShape ? CompositeKeyParamsImpl<Entity, Spec, Config['allowPartial'] extends true ? 1 : Extract<Config['depth'], number>> : never;
+declare class RotoriseError extends Error {
+    constructor(message: string);
+}
+type ProcessSpecType<Entity, Spec, Config extends SpecConfigShape> = Spec extends string ? DistributivePick<Entity, Spec> : Spec extends InputSpecShape ? CompositeKeyParamsImpl<Entity, Spec, Config['allowPartial'] extends true ? 1 : Extract<Config['depth'], number>> : Spec extends null | undefined ? unknown : ErrorMessage<'Invalid Spec: Expected string, InputSpecShape, null or undefined'>;
 type SpecConfig<Spec> = Spec extends string ? never : SpecConfigShape;
 type SpecConfigShape = {
     depth?: number;
     allowPartial?: boolean;
     enforceBoundary?: boolean;
 };
-type VariantType<Entity, K extends PropertyKey, V extends PropertyKey> = [
+type ExtractVariant<Entity, K extends PropertyKey, V extends PropertyKey> = [
+    Entity
+] extends [never] ? never : Extract<Entity, {
+    [k in K]: V;
+}>;
+type TagVariant<Entity, K extends PropertyKey, V extends PropertyKey> = [
     Entity
 ] extends [never] ? {
     [k in K]: V;
 } : Entity & {
     [k in K]: V;
 };
-type ProcessVariant<Entity, K extends PropertyKey, V extends PropertyKey, Spec extends DiscriminatedSchemaShape, Config extends SpecConfigShape> = VariantType<ProcessSpecType<VariantType<Entity, K, V>, Spec['spec'][V & keyof Spec['spec']], Config>, K, V>;
-type OptimizedAttributes<Entity, Spec, Config extends SpecConfigShape> = Spec extends DiscriminatedSchemaShape ? {
+type ProcessVariant<Entity, K extends PropertyKey, V extends PropertyKey, Spec extends DiscriminatedSchemaShape, Config extends SpecConfigShape, VariantSpec = Spec['spec'][V & keyof Spec['spec']]> = TagVariant<VariantSpec extends null | undefined ? unknown : ProcessSpecType<ExtractVariant<Entity, K, V>, VariantSpec, Config>, K, V>;
+type OptimizedAttributes<Entity, Spec, Config extends SpecConfigShape> = show<Spec extends DiscriminatedSchemaShape ? {
     [K in Spec['discriminator']]: {
         [V in keyof Spec['spec']]: ProcessVariant<Entity, K, V, Spec, Config>;
     }[keyof Spec['spec']];
-}[Spec['discriminator']] : ProcessSpecType<Entity, Spec, Config>;
-type ProcessKey<Entity, Spec, Separator extends string, NullAs extends never | undefined = never, Config extends SpecConfigShape = SpecConfigShape, Attributes = Pick<Entity, Spec & keyof Entity>> = [Entity] extends [never] ? never : Spec extends keyof Entity ? Replace<ValueOf<Attributes>, null, undefined> : Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, Exclude<Config['depth'], undefined>, Exclude<Config['allowPartial'], undefined>> : Spec extends null ? NullAs : never;
-type OptimizedBuildedKey<Entity, Spec, Separator extends string, Config extends SpecConfigShape, Attributes> = Entity extends unknown ? Spec extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Spec['spec'], ValueOf<Entity, Spec['discriminator']>>, Separator, undefined, Config, Attributes> : ProcessKey<Entity, Spec, Separator, undefined, Config, Attributes> : never;
+}[Spec['discriminator']] : ProcessSpecType<Entity, Spec, Config>>;
+type ProcessKey<Entity, Spec, Separator extends string, NullAs extends never | undefined = never, Config extends SpecConfigShape = SpecConfigShape, Attributes = Pick<Entity, Spec & keyof Entity>> = [Entity] extends [never] ? never : Spec extends keyof Entity ? Replace<ValueOf<Attributes>, null, undefined> : Spec extends InputSpecShape ? CompositeKeyBuilderImpl<Entity, Spec, Separator, Exclude<Config['depth'], undefined>, Exclude<Config['allowPartial'], undefined>> : Spec extends null | undefined ? NullAs : ErrorMessage<'Invalid Spec'>;
+type OptimizedBuiltKey<Entity, Spec, Separator extends string, Config extends SpecConfigShape, Attributes> = Entity extends unknown ? show<Spec extends DiscriminatedSchemaShape ? ProcessKey<Entity, ValueOf<Spec['spec'], ValueOf<Entity, Spec['discriminator']>>, Separator, undefined, Config, Attributes> : ProcessKey<Entity, Spec, Separator, undefined, Config, Attributes>> : never;
 type TableEntryDefinition<Entity, Schema, Separator extends string> = {
-    toEntry: <const ExactEntity extends Exact<Entity, ExactEntity>>(item: ExactEntity) => TableEntryImpl<ExactEntity, Schema, Separator>;
+    /**
+     * Converts a raw entity into a complete table entry with all keys computed.
+     * Use this when preparing items for insertion into DynamoDB.
+     */
+    toEntry: <const ExactEntity>(item: Exact<Entity, ExactEntity>) => TableEntryImpl<ExactEntity, Schema, Separator>;
+    /**
+     * Extracts the raw entity from a table entry by removing all computed keys.
+     * Use this when processing items retrieved from DynamoDB.
+     */
     fromEntry: <const Entry extends TableEntryImpl<Entity, Schema, Separator>>(entry: Entry) => DistributiveOmit<Entry, keyof Schema>;
+    /**
+     * Generates a specific key for the given entity attributes.
+     * Supports partial keys and depth limiting for query operations.
+     *
+     * @param key The name of the key to generate (e.g., 'PK', 'GSIPK').
+     * @param attributes the object containing the values needed to build the key.
+     * @param config Optional configuration for partial keys or depth limiting.
+     */
     key: <const Key extends keyof Schema, const Config extends SpecConfig<Spec>, const Attributes extends OptimizedAttributes<Entity, Spec, Config_>, Spec = Schema[Key], Config_ extends SpecConfigShape = [SpecConfigShape] extends [Config] ? {
         depth?: undefined;
         allowPartial?: undefined;
         enforceBoundary?: boolean;
-    } : Config>(key: Key, attributes: Attributes, config?: Config) => OptimizedBuildedKey<Attributes, Spec, Separator, Config_, Attributes>;
+    } : Config>(key: Key, attributes: Attributes, config?: Config) => OptimizedBuiltKey<Attributes, Spec, Separator, Config_, Attributes>;
+    /**
+     * A zero-runtime inference helper. Use this with `typeof` to get the
+     * total type of a table entry.
+     */
     infer: TableEntryImpl<Entity, Schema, Separator>;
+    /**
+     * Creates a proxy to generate property paths as strings.
+     * Useful for building UpdateExpressions or ProjectionExpressions.
+     *
+     * @example
+     * table.path().data.nested.property.toString() // returns "data.nested.property"
+     */
     path: () => TableEntryImpl<Entity, Schema, Separator>;
 };
-declare const tableEntry: <const Entity extends Record<string, unknown>>() => <const Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = "#">(schema: Schema, separator?: Separator) => TableEntryDefinition<Entity, Schema, Separator>;
+/**
+ * Entry point for defining a DynamoDB table schema with Rotorise.
+ *
+ * @template Entity The base entity type that this table represents.
+ * @returns A builder function that accepts the schema and an optional separator.
+ *
+ * Note: the double-call `<Entity>()(schema)` is required for partial type parameter inference.
+ *
+ * @example
+ * const userTable = tableEntry<User>()({
+ *   PK: ["orgId", "id"],
+ *   SK: "role"
+ * })
+ */
+declare const tableEntry: <const Entity extends Record<string, unknown>>() => <const Schema extends Record<string, FullKeySpec<Entity>>, Separator extends string = "#">(schema: Schema, ...[separator]: [Separator] extends [
+    ''
+] ? [ErrorMessage<'Separator must not be an empty string'>] : [separator?: Separator]) => TableEntryDefinition<Entity, Schema, Separator>;
 
-export { type CompositeKeyBuilder, type CompositeKeyParams, type CompositeKeyParamsImpl, type TableEntry, type TransformShape, tableEntry };
+export { type CompositeKeyBuilder, type CompositeKeyParams, type CompositeKeyParamsImpl, RotoriseError, type TableEntry, type TransformShape, tableEntry };

package/dist/Rotorise.js

@@ -1,4 +1,10 @@
 // src/Rotorise.ts
+var RotoriseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RotoriseError";
+  }
+};
 var chainableNoOpProxy = new Proxy(() => chainableNoOpProxy, {
   get: () => chainableNoOpProxy
 });
@@ -20,7 +26,7 @@ var createPathProxy = (path = "") => {
 var key = () => (schema, separator = "#") => (key2, attributes, config) => {
   const case_ = schema[key2];
   if (case_ === void 0) {
-    throw new Error(`Key ${key2.toString()} not found in schema`);
+    throw new RotoriseError(`Key ${key2.toString()} not found in schema`);
   }
   let structure;
   if (Array.isArray(case_)) {
@@ -28,13 +34,13 @@ var key = () => (schema, separator = "#") => (key2, attributes, config) => {
   } else if (typeof case_ === "object") {
     const discriminator = attributes[case_.discriminator];
     if (discriminator === void 0) {
-      throw new Error(
+      throw new RotoriseError(
         `Discriminator ${case_.discriminator.toString()} not found in ${JSON.stringify(attributes)}`
       );
     }
     const val = case_.spec[discriminator];
     if (val === void 0) {
-      throw new Error(
+      throw new RotoriseError(
         `Discriminator value ${discriminator?.toString()} not found in ${JSON.stringify(attributes)}`
       );
     }
@@ -74,7 +80,7 @@ var key = () => (schema, separator = "#") => (key2, attributes, config) => {
     } else if (config?.allowPartial) {
       break;
     } else {
-      throw new Error(
+      throw new RotoriseError(
         `buildCompositeKey: Attribute ${key3.toString()} not found in ${JSON.stringify(attributes)}`
       );
     }
@@ -86,8 +92,9 @@ var key = () => (schema, separator = "#") => (key2, attributes, config) => {
 };
 var toEntry = () => (schema, separator = "#") => (item) => {
   const entry = { ...item };
+  const buildKey = key()(schema, separator);
   for (const key_ in schema) {
-    const val = key()(schema, separator)(key_, item);
+    const val = buildKey(key_, item);
     if (val !== void 0) {
       entry[key_] = val;
     }
@@ -101,16 +108,20 @@ var fromEntry = () => (schema) => (entry) => {
   }
   return item;
 };
-var tableEntry = () => (schema, separator = "#") => {
+var tableEntry = () => (schema, ...[separator]) => {
+  const sep = separator ?? "#";
+  if (sep === "" || typeof sep !== "string") {
+    throw new RotoriseError("Separator must not be an empty string");
+  }
   return {
-    toEntry: toEntry()(schema, separator),
+    toEntry: toEntry()(schema, sep),
     fromEntry: fromEntry()(schema),
-    key: key()(schema, separator),
+    key: key()(schema, sep),
     infer: chainableNoOpProxy,
     path: () => createPathProxy()
   };
 };
-export {
-  tableEntry
-};
+
+export { RotoriseError, tableEntry };
+//# sourceMappingURL=Rotorise.js.map
 //# sourceMappingURL=Rotorise.js.map