{"id":19441296,"url":"https://github.com/wassim-k/sp-entity","last_synced_at":"2025-07-20T12:33:18.617Z","repository":{"id":40294815,"uuid":"133494309","full_name":"wassim-k/sp-entity","owner":"wassim-k","description":"Generate strongly-typed models from SharePoint lists in TypeScript","archived":false,"fork":false,"pushed_at":"2023-01-10T23:34:33.000Z","size":306,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-02T11:13:11.401Z","etag":null,"topics":["entity","framework","list","model","office365","paging","sharepoint","spfx","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wassim-k.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":"2018-05-15T09:39:30.000Z","updated_at":"2024-12-03T07:20:15.000Z","dependencies_parsed_at":"2023-02-08T20:45:29.806Z","dependency_job_id":null,"html_url":"https://github.com/wassim-k/sp-entity","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wassim-k/sp-entity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wassim-k%2Fsp-entity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wassim-k%2Fsp-entity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wassim-k%2Fsp-entity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wassim-k%2Fsp-entity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wassim-k","download_url":"https://codeload.github.com/wassim-k/sp-entity/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wassim-k%2Fsp-entity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266127212,"owners_count":23880420,"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":["entity","framework","list","model","office365","paging","sharepoint","spfx","typescript"],"created_at":"2024-11-10T15:34:57.709Z","updated_at":"2025-07-20T12:33:18.598Z","avatar_url":"https://github.com/wassim-k.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sp-entity\n\nGenerate strongly-typed models from SharePoint lists in TypeScript.\n\n## Table of Contents\n\n* [Prerequisites](#prerequisites)\n* [Supported SharePoint Versions](#supported-sharepoint-versions)\n* [Installation](#installation)\n* [Getting Started](#getting-started)\n* [Usage](#usage)\n    * [Get](#get)\n    * [Create](#create)\n    * [Update](#update)\n    * [Delete](#delete)\n    * [Query](#query)\n    * [Query with params](#query-with-params)\n    * [Query with $expand](#query-with-expand)\n    * [Query with paging](#query-with-paging)\n    * [SPFx Web Part](#spfx-web-part)\n* [Config](#config)\n* [Code Generation](#code-generation)\n* [Authentication](#authentication)\n* [Node Environment](#node-environment)\n* [IE10 Support](#ie10-support)\n* [License](#license)\n\n## Prerequisites\n\n* Node 6.9.0+\n* NPM 3+\n\n## Supported SharePoint Versions\n\n* SharePoint Online\n* SharePoint 2016\n* SharePoint 2013\n\n## Installation\n\nInstall sp-entity cli globally\n```bash\nnpm install -g @sp-entity/cli\n```\n\nAdd sp-entity as a dependency in project\n```bash\nnpm install @sp-entity/entity --save\n```\n\n## Getting Started\n\n### CLI\n\n```bash\n# login to sharepoint site\nspe login\n\n# generate dataContext folder with default sp-entity config\ncd {project folder}/src\nspe init\n\n# generate entity classes\nspe ./dataContext/spe.config.json\n```\n### Code\n\n```typescript\nimport { DataContext } from './dataContext/dataContext'; // generated by sp-entity\nimport { EmployeeItem } from './dataContext/employee'; // generated by sp-entity\n\n// initialize dataContext with default params (webUrl: _spPageContextInfo.webAbsoluteUrl)\nconst dataContext: DataContext = new DataContext();\ndataContext.employee.get(1).then((employee: EmployeeItem) =\u003e {\n    console.log(`${employee.firstName} ${employee.lastName}`); // Steve Rogers\n});\n```\n\n## Usage\n\nThe following usage examples are based on [sample generated code](#sample-generated-code) below.\n\n### Get\n\n```typescript\ndataContext.employee.get(1).then((employee: EmployeeItem) =\u003e {\n    console.log(employee);\n});\n\n/* Output\n{\n    id: 1,\n    title: 'Mr',\n    firstName: 'Steve',\n    lastName: 'Rogers',\n    officeId: 1,\n    active: false,\n    skills: ['TypeScript', 'SharePoint'],\n    created: '2018-01-01T00:00:00Z',\n    createdById: 6\n    ...\n} */\n```\n\n### Create\n\n```typescript\ndataContext.employee.create({\n    active: true,\n    title: 'Mr',\n    firstName: 'Steve',\n    lastName: 'Rogers',\n    officeId: 1\n});\n```\n\n### Update\n\n```typescript\nconst employee: EmployeeItem = await dataContext.employee.get(1);\nemployee.officeId = 5; // update office lookup\nemployee.skills = ['TypeScript', 'SharePoint']; // update skills\ndataContext.employee.update(employee); // commit changes\n\n// or\n\ndataContext.employee.update({\n    id: 1, // id property is required for updates\n    officeId: 5,\n    skills: ['TypeScript', 'SharePoint']\n});\n```\n\n### Delete\n\n```typescript\ndataContext.employee.delete(1);\n```\n\n###\n\n### Query\n\n```typescript\ndataContext.employee.query().then((employees: Array\u003cEmployeeItem\u003e) =\u003e {\n    // ...\n});\n```\n\n### Query with params\n\n```typescript\n// entity.fields property holds a map to list fields' internal names\n// using es6's object destructuring to get a reference to fields used in code\nconst { id, firstName, lastName, active, created } = dataContext.employee.fields;\n\nconst employees: Array\u003cEmployeeItem\u003e = await dataContext.employee.query({\n    $select: [id, firstName, lastName],\n    $filter: `${active} eq 1`,\n    $orderby: { orderBy: created, ascending: false }\n});\n```\n\n### Query with $expand\n\n```typescript\n// office is a property mapped from a lookup field\nconst { id, firstName, lastName, office } = dataContext.employee.fields;\n\nconst employees: Array\u003cEmployeeItem\u003e = await dataContext.employee.query({\n    // $select: ['Id','First_x0020_Name','Last_x0020_Name','Office/City','Office/Country']\n    $select: [id, firstName, lastName, office.city, office.country],\n    // $expand: ['Office']\n    $expand: [office.$name] // $name property holds a lookup's internal name\n});\n```\n\n### Query with paging\n\n```typescript\nimport { SpEntityPaged } from '@sp-entity/entity';\nimport { DataContext } from './dataContext/dataContext';\nimport { EmployeeFields, EmployeeItem } from './dataContext/employee';\n\nconst dataContext: DataContext = new DataContext();\n    \nconst { active } = dataContext.employee.fields;\nlet employeesPaged: SpEntityPaged\u003cEmployeeFields, EmployeeItem\u003e;\n\nemployeesPaged = await dataContext.employee.queryPaged({ $filter: `${active} eq 1`, $top: 5 /* page size */ });\nconsole.log(employeesPaged.page); // 0\n\nemployeesPaged = await employeesPaged.getNext();\nconsole.log(employeesPaged.page); // 1\n\nemployeesPaged = await employeesPaged.getNext();\nconsole.log(employeesPaged.page); // 2\n\nemployeesPaged = await employeesPaged.getPrev();\nconsole.log(employeesPaged.page); // 1\n\nemployeesPaged = await employeesPaged.getPrev();\nconsole.log(employeesPaged.page); // 0\n\nconst employees: Array\u003cEmployeeItem\u003e = employeesPaged.items;\n...\n```\n\n### SPFx Web Part\n\n```typescript\nimport { DataContext } from './dataContext/dataContext'; // generated by sp-entity\nimport { EmployeeItem } from './dataContext/employee'; // generated by sp-entity\n\nexport default class SpEntitySampleWebPart extends BaseClientSideWebPart\u003cISpEntitySampleWebPartProps\u003e {\n\n  private employees: Array\u003cEmployeeItem\u003e;\n\n  public async onInit(): Promise\u003cvoid\u003e {\n\n    // initialize dataContext with spfx context web url\n    const dataContext: DataContext = new DataContext(this.context.pageContext.web.absoluteUrl);\n    this.employees = await dataContext.employee.query();\n  }\n\n  private renderEmployees(): string {\n    return this.employees\n      .map((employee: EmployeeItem) =\u003e `\u003cdiv\u003e${employee.firstName} ${employee.lastName} works at ${employee.office.city}, ${employee.office.country} office\u003c/div\u003e`)\n      .join('')\n  }\n\n  ...\n}\n```\n\n## Config\n**spe init** command generates an **spe.config.json** file with all visible SharePoint lists in currently logged in site. Update config file to only include lists required in project and update their entityName if necessary, e.g.\n```javascript\n{\n    \"entities\": [\n        {\n            \"entityName\": \"Employee\",\n            \"listName\": \"Employees\"\n        },\n        {\n            \"entityName\": \"Office\",\n            \"listName\": \"Offices\"\n        }\n}\n```\n\n\u003e An **odataVerbose** flag is automatically added to generated config and set to true for all sp2013 environments. You may remove this flag if your 2013 environment is updated to SP1 and supports JSON light. Read [this post](http://www.spdoctor.net/Home/Article/using-json-light-in-sharepoint-server-2013) for more information.\n\n## Code Generation\n\nRunning **spe** command generates a folder for each entity in the config.\n\nThe [sample config](#config) above generates the following folder structure:\n* dataContext\n  * employee\n    * employeeFields.interface.ts\n    * employeeFields.ts \n    * employeeItem.ts\n  * office\n    * officeFields.interface.ts\n    * officeFields.ts \n    * officeItem.ts\n  * dataContext.ts\n  * spe.config.json\n\n### Sample Generated Code\n\n#### employeeFields.ts *(auto-generated)*\nAn *{entityName}Fields.ts* file is generated with mappings for default fields in the list returned by SharePoint's rest API. You may modify the file by adding/removing field mappings, updating property names and adding/removing expand fields for lookups (e.g. *office.city* and *office.country*).\n\n\u003e Make sure to run *spe* tool after modifying this file to automatically update related interfaces.\n```typescript\nimport { EmployeeFields } from './employeeFields.interface';\n\nexport const employeeFields: EmployeeFields = {\n\n    active: 'Active',\n    created: 'Created',\n    // each lookup field in the list is mapped to two properties:\n    // an expand property with id and title mappings by default\n    createdBy: { $name: 'Author', id: 'Id', title: 'Title' },\n    // and an id property\n    createdById: 'AuthorId',\n    firstName: 'First_x0020_Name',\n    id: 'Id',\n    lastName: 'Last_x0020_Name',\n    // city and country mappings have been added manually here\n    office: { $name: 'Office', id: 'Id', title: 'Title', city: 'City', country: 'Country' },\n    officeId: 'OfficeId',\n    picture: 'Picture',\n    permissions: 'EffectiveBasePermissions',\n    skills: 'Skills',\n    title: 'Title'\n};\n```\n\n#### employeeItem.ts *(auto-generated)*\n```typescript\nimport { iso8601Date, SpBasePermissions, SpUrlValue } from '@sp-entity/entity';\n\nexport interface EmployeeItem {\n\n    active: boolean;\n    readonly created: iso8601Date;\n    readonly createdBy: { id: number, title: string };\n    readonly createdById: number;\n    firstName: string;\n    readonly id: number;\n    lastName: string;\n    readonly office: { city: string, country: string, id: number, title: string };\n    officeId: number;\n    readonly permissions: SpBasePermissions;\n    picture: SpUrlValue;\n    skills: Array\u003cstring\u003e;\n    title: string;\n}\n\n```\n\n#### dataContext.ts *(auto-generated)*\n```typescript\nimport { SpEntity } from '@sp-entity/entity';\nimport { EmployeeFields, employeeFields, EmployeeItem, employeeListName } from './employee';\nimport { OfficeFields, officeFields, OfficeItem, officeListName } from './office';\n\nexport class DataContext {\n\n    public readonly employee: SpEntity\u003cEmployeeFields, EmployeeItem\u003e;\n    public readonly office: SpEntity\u003cOfficeFields, OfficeItem\u003e;\n\n    public constructor(webUrl?: string) {\n\n        this.employee = new SpEntity(employeeListName, employeeFields, webUrl);\n        this.office = new SpEntity(officeListName, officeFields, webUrl);\n    }\n}\n```\n\n## Authentication\n**spe login** and **spe logout** commands can be used to store/delete encrypted credentials for context sharepoint site.\nUsing **spe** cli without logging in first will prompt for credentials every time.\n\nLogin wizard is provided by the following awesome libraries:\n* [node-sp-auth](https://github.com/s-KaiNet/node-sp-auth) by Sergei Sergeev [@s-KaiNet](https://github.com/s-KaiNet)\n* [node-sp-auth-config](https://github.com/koltyakov/node-sp-auth-config) by Andrew Koltyakov [@koltyakov](https://github.com/koltyakov)\n\n## Node Environment\nIn order to use sp-entity in a node environment, a fetch client factory must be provided using **setup** method\n\nInstall [pnp-auth](https://github.com/SharePoint-NodeJS/pnp-auth) dependency\n\n```bash\nnpm install pnp-auth --save\n```\n\nSetup sp-entity's **fetchClientFactory**\n\n```typescript\nimport { setup } from '@sp-entity/entity';\nimport { IAuthOptions } from 'node-sp-auth';\nimport NodeFetchClient from 'pnp-auth/lib/NodeFetchClient';\n\nconst siteUrl: string = 'https://contoso.sharepoint.com/sites/example';\n\nconst authOptions: IAuthOptions = {\n    username: 'user@contoso.onmicrosoft.com',\n    password: 'password'\n};\n\nsetup({\n    fetchClientFactory: () =\u003e {\n        return new NodeFetchClient(authOptions, siteUrl) as GlobalFetch;\n    }\n});\n\nconst dataContext: DataContext = new DataContext();\n...\n```\n\n## IE10 Support\nFollowing polyfills are required for using sp-entity in IE10\n\n* [es6-promise](https://github.com/stefanpenner/es6-promise)\n* [whatwg-fetch](https://github.com/github/fetch)\n\n\u003e This is not required for SPFx projects as they include above polyfills by default\n\n## License\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwassim-k%2Fsp-entity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwassim-k%2Fsp-entity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwassim-k%2Fsp-entity/lists"}