{"id":18389297,"url":"https://github.com/rightpoint/rzimport","last_synced_at":"2025-04-07T02:34:13.998Z","repository":{"id":17303682,"uuid":"20074204","full_name":"Rightpoint/RZImport","owner":"Rightpoint","description":"Automatic importing of data from NSDictionary to Cocoa objects","archived":false,"fork":false,"pushed_at":"2016-02-29T18:26:11.000Z","size":208,"stargazers_count":18,"open_issues_count":5,"forks_count":6,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-04-01T12:53:08.630Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rightpoint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-05-22T19:30:21.000Z","updated_at":"2018-11-01T08:46:32.000Z","dependencies_parsed_at":"2022-08-25T13:02:28.194Z","dependency_job_id":null,"html_url":"https://github.com/Rightpoint/RZImport","commit_stats":null,"previous_names":["raizlabs/rzimport"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rightpoint%2FRZImport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rightpoint%2FRZImport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rightpoint%2FRZImport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rightpoint%2FRZImport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rightpoint","download_url":"https://codeload.github.com/Rightpoint/RZImport/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247583254,"owners_count":20961998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T01:42:27.040Z","updated_at":"2025-04-07T02:34:08.988Z","avatar_url":"https://github.com/Rightpoint.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"RZImport\n============\n\n[![Build Status](https://travis-ci.org/Raizlabs/RZImport.svg)](https://travis-ci.org/Raizlabs/RZImport)\n[![Version](https://img.shields.io/cocoapods/v/RZImport.svg?style=flat)](http://cocoadocs.org/docsets/RZImport)\n\nTired of writing boilerplate to import deserialized API responses to model objects?\n\nTired of dealing with dozens and dozens of string keys?\n\nRZImport is here to help!\n\nRZImport is a category on `NSObject` and an accompanying optional protocol for creating and updating model objects in your iOS applications. It's particularly useful for importing objects from deserialized JSON HTTP responses in REST API's, but it works with any `NSDictionary` or array of dictionaries that you need to convert to native model objects.\n\n#### Convenient\n\nProperty names are inferred from similarly named string keys in an `NSDictionary` and performs automatic type-conversion whenever possible. No need to reference string constants all over the place, just name your properties in a similar way to the keys in the dictionary and let RZImport handle it for you.\n\nRZImport automatically performs case-insensitive matches between property names and key names, ignoring underscores. For example, all of the following keys will map to a property named `firstName`:\n\n- `firstName`\n- `FirstName`\n- `first_name`\n- `FiRst_NAme`\n\n\n#### Flexible\n\nCan't name your properties the same as the keys in the dictionary? Need to perform extra validation or import logic? No problem! The `RZImportable` protocol has hooks for specifying custom mappings, custom import logic and validation on a per-key basis, and more!\n\n#### Performant\n\nKey/property mappings are created once and cached, so once an object type has been imported once, subsequent imports are super-speedy!\n\n#### Example\n\n```obj-c\n@interface Person : NSObject\n\n@property (copy, nonatomic) NSNumber *ID;\n@property (copy, nonatomic) NSString *firstName;\n@property (copy, nonatomic) NSString *lastName;\n\n@end\n\n...\n\n// Dictionary with some key/value pairs representing a person\nNSDictionary *myDictionary = @{\n    @\"id\" : @100,\n    @\"first_name\" : @\"Bob\",\n    @\"last_name\" : @\"Smith\"\n};\n\n// Create a new Person instance by automatically inferring key/property mappings\nPerson *newPerson = [Person rzi_objectFromDictionary:myDictionary];\nNSLog(@\"ID: %@ Name: %@ %@\", newPerson.ID, newPerson.firstName, newPerson.lastName);\n```\n\n##### Console Output:\n\n```\nID: 100 Name: Bob Smith\n```\n## Installation\n\n#### CocoaPods (Preferred)\n\nAdd the following to your podfile and run `pod install`:\n\n```\npod 'RZImport', '~\u003e 1.0'\n```\n\nThis project uses semantic versioning, so the version number can be changed to suit your project's needs as future versions are released. See the [CocoaPods guides](http://guides.cocoapods.org/using/the-podfile.html) for more details.\n\n#### Manual Installation\n\nSimply copy the files in the `Classes` directory into your project, add them to your target, and off you go!\n\n**Note**: The `Private` directory contains private headers that are not intended for public usage.\n\n## Documentation\n\n##### For most in-depth and up-to-date documentation, please read the Apple-doc commented header files in the source code, or visit the [documentation page](http://cocoadocs.org/docsets/RZImport) on CocoaDocs.\n\n### Basic Usage\n\nRZImport can be used to create model objects from a either a dictionary or an array of dictionaries.\n\n```obj-c\n#import \"NSObject+RZImport.h\"\n\n...\n\n- (void)fetchThePeople\n{\n    [self.apiClient get:@\"/people\" completion:^(NSData *responseData, NSError *error) {\n\n        if ( responseData ) {\n            NSError *jsonErr = nil;\n            id deserializedResponse = [NSJSONSerialization JSONObjectWithData:responseData\n                                                                      options:kNilOptions\n                                                                        error:\u0026jsonErr];\n            if ( deserializedResponse ) {\n                // convert to native objects\n                if ( [deserializedResponse isKindOfClass:[NSDictionary class]] ) {\n                    Person *newPerson = [Person rzi_objectFromDictionary:deserializedResponse];\n                    // ... do something with the person ...\n                }\n                else if ( [deserializedResponse isKindOfClass:[NSArray class]] ) {\n                    NSArray *people = [Person rzi_objectsFromArray:deserializedResponse];\n                    // ... do something with the people ...\n                }\n            }\n            else {\n                // Handle jsonErr\n            }\n        }\n    }];\n}\n\n```\n\nYou can also update an existing object instance from a dictionary.\n\n```obj-c\nPerson *myPerson = self.person;\n[myPerson rzi_importValuesFromDict:someDictionary];\n```\n\n### Custom Mappings\n\nIf you need to provide a custom mapping from a dictionary key or keypath to a property name, implement the `RZImportable` protocol on your model class. Custom mappings will take precedence over inferred mappings, but both can be used for the same class.\n\n```obj-c\n#import \"RZImportable.h\"\n\n@interface MyModelClass : NSObject \u003cRZImportable\u003e\n\n@property (copy, nonatomic) NSNumber *objectID;\n@property (copy, nonatomic) NSString *zipCode;\n\n@end\n\n\n@implementation MyModelClass\n\n+ (NSDictionary *)rzi_customKeyMappings\n{\n    // Map dictionary key \"zip\" to property \"zipCode\"\n    // and dictionary key \"id\" to property \"objectID\"\n    return @{\n        @\"zip\" : @\"zipCode\",\n        @\"id\" : @\"objectID\"\n    };\n}\n\n@end\n\n```\n\nYou can also prevent RZImport from importing a value for a particular key, or import the value of a key using your own custom logic.\n\n```obj-c\n- (BOOL)rzi_shouldImportValue:(id)value forKey:(NSString *)key;\n{\n    if ( [key isEqualToString:@\"zip\"] ) {\n        // validation - must be a string that only contains numbers\n        if ( [value isKindOfClass:[NSString class]] ) {\n            return ([value rangeOfCharacterFromSet:[[NSCharacterSet decimalDigitCharacterSet] invertedSet]].location == NSNotFound);\n        }\n        return NO;\n    }\n    else if ( [key isEqualToString:@\"address\"] ) {\n        if ( [value isKindOfClass:[NSDictionary class]] ) {\n            // custom import logic\n            self.address = [Address rzi_objectFromDictionary:value];\n        }\n        return NO;\n    }\n    return YES;\n}\n\n```\n\n### Nested Dictionaries\n\nIf you are importing a dictionary with sub-dictionaries that correspond to objects that you want to also be imported using RZImport, you can implement the `RZImportable` protocol and return the keys from `rzi_nestedObjectKeys`.\n\n```obj-c\n@interface Job : NSObject\n\n@property (copy, nonatomic) NSString *jobTitle;\n@property (copy, nonatomic) NSString *companyName;\n\n@end\n\n@interface Person : NSObject \u003cRZImportable\u003e\n\n@property (strong, nonatomic) Job *job;\n@property (copy, nonatomic) NSString *firstName;\n\n@end\n\n@implementation Person\n\n+ (NSArray *)rzi_nestedObjectKeys\n{\n    return @[ @\"job\" ];\n}\n\n@end\n\n...\n- (void)createPersonWithJob\n{\n    NSDictionary *personData = @{\n                    @\"firstName\" : @\"John\",\n                    @\"job\" : @{\n                        @\"jobTitle\" : @\"Software Developer\",\n                        @\"companyName\" : @\"Raizlabs\"\n                    }\n                };\n    Person *p = [Person rz_objectFromDictionary:personData];\n}\n```\n\n### Uniquing Objects\n\n`RZImportable` also has a handy method that you can implement on your classes to prevent duplicate objects from being created when using `rzi_objectFromDictionary:` or `rzi_objectsFromArray:`.\n\n```obj-c\n+ (id)rzi_existingObjectForDict:(NSDictionary *)dict\n{\n    // If there is already an object in the data store with the same ID, return it.\n    // The existing instance will be updated and returned instead of a new instance.\n    NSNumber *objID = [dict objectForKey:@\"id\"];\n    if ( objID != nil ) {\n        return [[DataStore sharedInstance] objectWithClassName:@\"Person\" forId:objID];\n    }\n    return nil;\n}\n```\n\n## Known Issues\n\nRZImport uses the default designated initializer `init` when it creates new object instances, therefore it cannot be used out-of-the-box with classes that require another designated initializer. However, to get around this, you can override `+rzi_existingObjectForDict:` on any class to *always* return a new object created with the proper initializer (or an existing object).\n\nFor example, RZImport cannot be used out-of-the-box to create valid instances of a subclass of `NSManagedObject`, since managed objects must be initialized with an entity description. However, there is no reason it will not work for updating existing instances of a subclass of `NSManagedObject` from a dictionary, or by overriding `+rzi_existingObjectForDict` to return a new object inserted into the correct managed object context.\n\n**If you are interested in using RZImport with CoreData, check out [RZVinyl](https://github.com/Raizlabs/RZVinyl)**\n\n## Maintainers\n[arrouse](https://github.com/arrouse) ([@arrouse88](http://twitter.com/arrouse88))\n\n[nbonatsakis](https://github.com/nbonatsakis) ([@nickbona](http://twitter.com/nickbona))\n\n[KingOfBrian](https://github.com/KingOfBrian) ([@KingOfBrian](http://twitter.com/KingOfBrian))\n\n[mattThousand](https://github.com/mattThousand) ([@mattThousand ](http://twitter.com/mattThousand))\n\n[SpencerP](https://github.com/SpencerP)\n\n[LFabien](https://github.com/LFabien)\n\n## Contributors\n\n[ndonald2](https://github.com/ndonald2) ([@infrasonick](http://twitter.com/infrasonick)) \n\n## License\n\nRZImport is licensed under the MIT license. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frightpoint%2Frzimport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frightpoint%2Frzimport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frightpoint%2Frzimport/lists"}